@open-core/framework 0.1.0-alpha.1

package/dist/server/services/parallel/worker-pool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Worker Pool
+ *
+ * Abstract worker pool that supports different backends.
+ * In FiveM environment, falls back to async execution.
+ * Can be extended to support native workers when available.
+ */
+import type { WorkerPoolConfig, WorkerInfo, WorkerMessage } from './types';
+type EventCallback = (...args: unknown[]) => void;
+/**
+ * Simple event emitter (FiveM compatible)
+ */
+declare class SimpleEventEmitter {
+    private events;
+    on(event: string, callback: EventCallback): void;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, ...args: unknown[]): void;
+}
+export declare class WorkerPool extends SimpleEventEmitter {
+    private workers;
+    private taskQueue;
+    private config;
+    private workerIdCounter;
+    private cleanupInterval;
+    private isShuttingDown;
+    private useNativeWorkers;
+    constructor(config?: Partial<WorkerPoolConfig>);
+    /**
+     * Detect if native worker threads are available
+     */
+    private detectWorkerSupport;
+    /**
+     * Check if using native workers
+     */
+    get isNative(): boolean;
+    /**
+     * Execute a task
+     */
+    execute(message: WorkerMessage): Promise<unknown>;
+    /**
+     * Get current pool statistics
+     */
+    getStats(): {
+        totalWorkers: number;
+        idleWorkers: number;
+        busyWorkers: number;
+        queuedTasks: number;
+        isNative: boolean;
+    };
+    /**
+     * Get all worker info
+     */
+    getWorkerInfo(): WorkerInfo[];
+    /**
+     * Shutdown the pool gracefully
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Spawn a new virtual worker
+     */
+    private spawnWorker;
+    /**
+     * Find an idle worker
+     */
+    private findIdleWorker;
+    /**
+     * Assign a task to a worker
+     */
+    private assignTask;
+    /**
+     * Handle task timeout
+     */
+    private handleTaskTimeout;
+    /**
+     * Process queued tasks
+     */
+    private processQueue;
+    /**
+     * Cleanup idle workers
+     */
+    private cleanupIdleWorkers;
+}
+export {};

package/dist/server/services/parallel/worker-pool.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * Worker Pool
+ *
+ * Abstract worker pool that supports different backends.
+ * In FiveM environment, falls back to async execution.
+ * Can be extended to support native workers when available.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = void 0;
+const DEFAULT_CONFIG = {
+    minWorkers: 0,
+    maxWorkers: 4,
+    idleTimeout: 30000,
+    taskTimeout: 60000,
+};
+/**
+ * Simple event emitter (FiveM compatible)
+ */
+class SimpleEventEmitter {
+    constructor() {
+        this.events = new Map();
+    }
+    on(event, callback) {
+        const callbacks = this.events.get(event) || [];
+        callbacks.push(callback);
+        this.events.set(event, callbacks);
+    }
+    off(event, callback) {
+        const callbacks = this.events.get(event) || [];
+        const index = callbacks.indexOf(callback);
+        if (index !== -1) {
+            callbacks.splice(index, 1);
+        }
+    }
+    emit(event, ...args) {
+        const callbacks = this.events.get(event) || [];
+        for (const callback of callbacks) {
+            try {
+                callback(...args);
+            }
+            catch (_a) {
+                // Ignore callback errors
+            }
+        }
+    }
+}
+/**
+ * Virtual worker that executes tasks asynchronously
+ * Used as fallback when native workers aren't available
+ */
+class VirtualWorker {
+    constructor(id) {
+        this._status = 'idle';
+        this.tasksCompleted = 0;
+        this.lastActiveAt = Date.now();
+        this.currentTask = null;
+        this.id = id;
+    }
+    get status() {
+        return this._status;
+    }
+    get info() {
+        var _a, _b;
+        return {
+            id: this.id,
+            status: this._status,
+            currentTaskId: (_b = (_a = this.currentTask) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : null,
+            tasksCompleted: this.tasksCompleted,
+            lastActiveAt: this.lastActiveAt,
+        };
+    }
+    async execute(task) {
+        this._status = 'busy';
+        this.currentTask = task;
+        const startTime = performance.now();
+        try {
+            // Execute the function
+            const fn = new Function('input', `return (${task.message.functionBody})(input)`);
+            const result = fn(task.message.input);
+            const executionTime = performance.now() - startTime;
+            this.tasksCompleted++;
+            this.lastActiveAt = Date.now();
+            this._status = 'idle';
+            this.currentTask = null;
+            return {
+                id: task.id,
+                success: true,
+                result,
+                executionTime,
+            };
+        }
+        catch (error) {
+            const executionTime = performance.now() - startTime;
+            this._status = 'idle';
+            this.currentTask = null;
+            return {
+                id: task.id,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                executionTime,
+            };
+        }
+    }
+    terminate() {
+        this._status = 'terminated';
+        this.currentTask = null;
+    }
+}
+class WorkerPool extends SimpleEventEmitter {
+    constructor(config = {}) {
+        super();
+        this.workers = new Map();
+        this.taskQueue = [];
+        this.workerIdCounter = 0;
+        this.cleanupInterval = null;
+        this.isShuttingDown = false;
+        this.useNativeWorkers = false;
+        this.config = Object.assign(Object.assign({}, DEFAULT_CONFIG), config);
+        // Check if native workers are available
+        this.detectWorkerSupport();
+        // Start cleanup interval
+        this.cleanupInterval = setInterval(() => this.cleanupIdleWorkers(), 10000);
+        // Spawn minimum workers
+        for (let i = 0; i < this.config.minWorkers; i++) {
+            this.spawnWorker();
+        }
+    }
+    /**
+     * Detect if native worker threads are available
+     */
+    detectWorkerSupport() {
+        try {
+            // Try to detect worker_threads module
+            // In FiveM this will fail, which is expected
+            this.useNativeWorkers = false;
+        }
+        catch (_a) {
+            this.useNativeWorkers = false;
+        }
+    }
+    /**
+     * Check if using native workers
+     */
+    get isNative() {
+        return this.useNativeWorkers;
+    }
+    /**
+     * Execute a task
+     */
+    async execute(message) {
+        if (this.isShuttingDown) {
+            throw new Error('Worker pool is shutting down');
+        }
+        return new Promise((resolve, reject) => {
+            const task = {
+                id: message.id,
+                message,
+                resolve,
+                reject,
+                startTime: Date.now(),
+                timeoutId: null,
+            };
+            // Set timeout
+            task.timeoutId = setTimeout(() => {
+                this.handleTaskTimeout(task);
+            }, this.config.taskTimeout);
+            // Find an idle worker
+            const idleWorker = this.findIdleWorker();
+            if (idleWorker) {
+                this.assignTask(idleWorker, task);
+            }
+            else if (this.workers.size < this.config.maxWorkers) {
+                const newWorker = this.spawnWorker();
+                if (newWorker) {
+                    this.assignTask(newWorker, task);
+                }
+                else {
+                    this.taskQueue.push(task);
+                }
+            }
+            else {
+                this.taskQueue.push(task);
+            }
+        });
+    }
+    /**
+     * Get current pool statistics
+     */
+    getStats() {
+        let idle = 0;
+        let busy = 0;
+        for (const worker of this.workers.values()) {
+            if (worker.status === 'idle')
+                idle++;
+            else if (worker.status === 'busy')
+                busy++;
+        }
+        return {
+            totalWorkers: this.workers.size,
+            idleWorkers: idle,
+            busyWorkers: busy,
+            queuedTasks: this.taskQueue.length,
+            isNative: this.useNativeWorkers,
+        };
+    }
+    /**
+     * Get all worker info
+     */
+    getWorkerInfo() {
+        return Array.from(this.workers.values()).map((w) => w.info);
+    }
+    /**
+     * Shutdown the pool gracefully
+     */
+    async shutdown() {
+        this.isShuttingDown = true;
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Reject all queued tasks
+        for (const task of this.taskQueue) {
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            task.reject(new Error('Worker pool shutdown'));
+        }
+        this.taskQueue = [];
+        // Terminate all workers
+        for (const worker of this.workers.values()) {
+            worker.terminate();
+        }
+        this.workers.clear();
+    }
+    /**
+     * Spawn a new virtual worker
+     */
+    spawnWorker() {
+        try {
+            const id = this.workerIdCounter++;
+            const worker = new VirtualWorker(id);
+            this.workers.set(id, worker);
+            this.emit('workerSpawned', id);
+            return worker;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * Find an idle worker
+     */
+    findIdleWorker() {
+        for (const worker of this.workers.values()) {
+            if (worker.status === 'idle') {
+                return worker;
+            }
+        }
+        return null;
+    }
+    /**
+     * Assign a task to a worker
+     */
+    async assignTask(worker, task) {
+        try {
+            const response = await worker.execute(task);
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            if (response.success) {
+                task.resolve(response.result);
+            }
+            else {
+                task.reject(new Error(response.error || 'Unknown worker error'));
+            }
+            this.emit('taskCompleted', {
+                taskId: response.id,
+                workerId: worker.id,
+                executionTime: response.executionTime,
+            });
+            // Process next queued task
+            this.processQueue();
+        }
+        catch (error) {
+            if (task.timeoutId)
+                clearTimeout(task.timeoutId);
+            task.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Handle task timeout
+     */
+    handleTaskTimeout(task) {
+        task.reject(new Error('Task timeout'));
+        // Remove from queue if present
+        const queueIndex = this.taskQueue.findIndex((t) => t.id === task.id);
+        if (queueIndex !== -1) {
+            this.taskQueue.splice(queueIndex, 1);
+        }
+    }
+    /**
+     * Process queued tasks
+     */
+    processQueue() {
+        while (this.taskQueue.length > 0) {
+            const idleWorker = this.findIdleWorker();
+            if (idleWorker) {
+                const task = this.taskQueue.shift();
+                this.assignTask(idleWorker, task);
+            }
+            else if (this.workers.size < this.config.maxWorkers) {
+                const newWorker = this.spawnWorker();
+                if (newWorker) {
+                    const task = this.taskQueue.shift();
+                    this.assignTask(newWorker, task);
+                }
+                else {
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+    }
+    /**
+     * Cleanup idle workers
+     */
+    cleanupIdleWorkers() {
+        if (this.isShuttingDown)
+            return;
+        const now = Date.now();
+        const workersToRemove = [];
+        for (const [id, worker] of this.workers) {
+            if (worker.status === 'idle' &&
+                now - worker.info.lastActiveAt > this.config.idleTimeout &&
+                this.workers.size > this.config.minWorkers) {
+                workersToRemove.push(id);
+            }
+        }
+        for (const id of workersToRemove) {
+            const worker = this.workers.get(id);
+            if (worker) {
+                worker.terminate();
+                this.workers.delete(id);
+                this.emit('workerExit', { workerId: id, code: 0 });
+            }
+        }
+    }
+}
+exports.WorkerPool = WorkerPool;

package/dist/server/services/parallel/worker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Worker Script
+ *
+ * This file is reserved for future native worker thread support.
+ * Currently, the WorkerPool uses virtual workers that execute
+ * tasks asynchronously on the main thread with yielding.
+ *
+ * When FiveM or the target environment supports native worker threads,
+ * this script can be used as the worker entry point.
+ */
+import type { WorkerMessage, WorkerResponse } from './types';
+/**
+ * Execute a compute function from its string body
+ */
+export declare function executeCompute(functionBody: string, input: unknown): unknown;
+/**
+ * Process a worker message and return a response
+ */
+export declare function processMessage(message: WorkerMessage): WorkerResponse;

package/dist/server/services/parallel/worker.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Worker Script
+ *
+ * This file is reserved for future native worker thread support.
+ * Currently, the WorkerPool uses virtual workers that execute
+ * tasks asynchronously on the main thread with yielding.
+ *
+ * When FiveM or the target environment supports native worker threads,
+ * this script can be used as the worker entry point.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCompute = executeCompute;
+exports.processMessage = processMessage;
+/**
+ * Execute a compute function from its string body
+ */
+function executeCompute(functionBody, input) {
+    const fn = new Function('input', `return (${functionBody})(input)`);
+    return fn(input);
+}
+/**
+ * Process a worker message and return a response
+ */
+function processMessage(message) {
+    const startTime = performance.now();
+    try {
+        const result = executeCompute(message.functionBody, message.input);
+        const executionTime = performance.now() - startTime;
+        return {
+            id: message.id,
+            success: true,
+            result,
+            executionTime,
+        };
+    }
+    catch (error) {
+        const executionTime = performance.now() - startTime;
+        return {
+            id: message.id,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            executionTime,
+        };
+    }
+}
+// Note: Native worker thread initialization would go here
+// when the runtime supports it. For now, this module exports
+// utilities that can be used by the virtual worker implementation.

package/dist/server/services/persistence.service.d.ts

@@ -0,0 +1,59 @@
+import type { Player } from '../entities/player';
+/**
+ * Internal service that orchestrates player data persistence.
+ *
+ * This service manages the lifecycle of persistence hooks and auto-save intervals.
+ * It is used internally by the framework and should not be instantiated directly.
+ */
+export declare class PlayerPersistenceService {
+    private provider;
+    private autoSaveIntervals;
+    private initialized;
+    /**
+     * Initializes the persistence service by resolving the provider from DI.
+     * Called during bootstrap if a provider is registered.
+     */
+    initialize(): void;
+    /**
+     * Whether persistence is enabled (provider is configured).
+     */
+    get isEnabled(): boolean;
+    /**
+     * Handles player session load - called when a player joins.
+     *
+     * @param player - The player who just joined
+     */
+    handleSessionLoad(player: Player): Promise<void>;
+    /**
+     * Handles player session save - called when a player disconnects.
+     *
+     * @param player - The player who is disconnecting
+     */
+    handleSessionSave(player: Player): Promise<void>;
+    /**
+     * Manually triggers a save for a specific player.
+     *
+     * @param player - The player whose data should be saved
+     */
+    savePlayer(player: Player): Promise<void>;
+    /**
+     * Saves all connected players' data.
+     * Useful for server shutdown or periodic global saves.
+     *
+     * @param players - Array of all connected players
+     */
+    saveAllPlayers(players: Player[]): Promise<void>;
+    /**
+     * Starts the auto-save interval for a player.
+     */
+    private startAutoSave;
+    /**
+     * Stops the auto-save interval for a player.
+     */
+    private stopAutoSave;
+    /**
+     * Stops all auto-save intervals.
+     * Called during server shutdown.
+     */
+    stopAllAutoSaves(): void;
+}