@open-core/framework 1.0.1-beta.1

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

@@ -0,0 +1,188 @@
+/**
+ * ParallelCompute Module Types
+ *
+ * Provides type definitions for the parallel computation system.
+ */
+/**
+ * Task execution mode
+ */
+export type ExecutionMode = 'auto' | 'sync' | 'parallel';
+/**
+ * Worker pool configuration
+ */
+export interface WorkerPoolConfig {
+    /** Minimum number of workers to keep alive */
+    minWorkers: number;
+    /** Maximum number of workers to spawn */
+    maxWorkers: number;
+    /** Time in ms before idle workers are terminated */
+    idleTimeout: number;
+    /** Maximum time in ms a task can run before timeout */
+    taskTimeout: number;
+}
+/**
+ * Options for defining a parallel task
+ */
+export interface ParallelTaskOptions<TInput, TOutput> {
+    /** Unique name for the task (used for debugging and metrics) */
+    name: string;
+    /**
+     * Function to estimate computational cost based on input.
+     * Higher values = more likely to use worker.
+     * Return a number representing relative complexity.
+     */
+    estimateCost?: (input: TInput) => number;
+    /**
+     * If estimated cost exceeds this threshold, automatically use worker.
+     * Default: 10000
+     */
+    workerThreshold?: number;
+    /**
+     * The compute function to execute.
+     * MUST be pure (no closures, no external dependencies).
+     * Will be serialized and sent to worker.
+     */
+    compute: (input: TInput) => TOutput;
+    /**
+     * Optional function to split input into chunks for multiple workers.
+     * Enables parallel processing across multiple workers.
+     */
+    chunker?: (input: TInput, workerCount: number) => TInput[];
+    /**
+     * Optional function to merge results from multiple chunks.
+     * Required if chunker is provided.
+     */
+    merger?: (results: TOutput[]) => TOutput;
+}
+/**
+ * A defined parallel task that can be executed
+ */
+export interface ParallelTask<TInput, TOutput> {
+    /** Task name */
+    readonly name: string;
+    /** Task options */
+    readonly options: ParallelTaskOptions<TInput, TOutput>;
+    /**
+     * Execute the task with automatic mode selection.
+     * Uses worker if estimated cost exceeds threshold.
+     */
+    run(input: TInput): Promise<TOutput>;
+    /**
+     * Force execution on main thread (synchronous).
+     */
+    sync(input: TInput): TOutput;
+    /**
+     * Force execution on worker thread.
+     */
+    parallel(input: TInput): Promise<TOutput>;
+    /**
+     * Execute with multiple workers (requires chunker/merger).
+     */
+    distributed(input: TInput, workerCount?: number): Promise<TOutput>;
+}
+/**
+ * Message sent to worker
+ */
+export interface WorkerMessage {
+    id: string;
+    taskName: string;
+    functionBody: string;
+    input: unknown;
+}
+/**
+ * Response from worker
+ */
+export interface WorkerResponse {
+    id: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    executionTime: number;
+}
+/**
+ * Worker status
+ */
+export type WorkerStatus = 'idle' | 'busy' | 'terminated';
+/**
+ * Worker info for pool management
+ */
+export interface WorkerInfo {
+    id: number;
+    status: WorkerStatus;
+    currentTaskId: string | null;
+    tasksCompleted: number;
+    lastActiveAt: number;
+}
+/**
+ * Metrics for parallel compute service
+ */
+export interface ParallelComputeMetrics {
+    /** Total tasks executed */
+    totalTasks: number;
+    /** Tasks executed on main thread */
+    syncTasks: number;
+    /** Tasks executed on workers */
+    parallelTasks: number;
+    /** Tasks that failed */
+    failedTasks: number;
+    /** Average execution time in ms */
+    avgExecutionTime: number;
+    /** Total time saved by parallelization (estimated) */
+    estimatedTimeSaved: number;
+    /** Current active workers */
+    activeWorkers: number;
+    /** Peak worker count */
+    peakWorkers: number;
+}
+/**
+ * Task execution result with timing info
+ */
+export interface TaskResult<T> {
+    result: T;
+    executionTime: number;
+    mode: 'sync' | 'parallel' | 'distributed';
+    workerCount?: number;
+}
+/**
+ * Built-in compute functions for common operations
+ */
+export interface BuiltInComputes {
+    /**
+     * Filter entities by distance from a position
+     */
+    filterByDistance: <T extends {
+        x: number;
+        y: number;
+        z: number;
+    }>(input: {
+        entities: T[];
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        radius: number;
+    }) => T[];
+    /**
+     * Sort entities by distance from a position
+     */
+    sortByDistance: <T extends {
+        x: number;
+        y: number;
+        z: number;
+    }>(input: {
+        entities: T[];
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }) => T[];
+    /**
+     * Batch process items with a transform function
+     */
+    batchProcess: <T, R>(input: {
+        items: T[];
+        transform: string;
+    }) => R[];
+}

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

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * ParallelCompute Module Types
+ *
+ * Provides type definitions for the parallel computation system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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.