@open-core/framework 0.1.0-alpha.1

package/dist/server/services/parallel/parallel-compute.service.js

@@ -0,0 +1,449 @@
+"use strict";
+/**
+ * ParallelCompute Service
+ *
+ * Provides an ergonomic API for parallel computation.
+ * Uses virtual workers in FiveM environment, with async execution
+ * that yields to the event loop for better performance.
+ *
+ * Automatically decides whether to run synchronously or asynchronously
+ * based on estimated computational cost.
+ */
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findClosest = exports.sortByDistance = exports.filterByDistance = exports.ParallelComputeService = void 0;
+exports.getParallelComputeService = getParallelComputeService;
+exports.initParallelCompute = initParallelCompute;
+exports.shutdownParallelCompute = shutdownParallelCompute;
+exports.defineTask = defineTask;
+exports.defineBatchTransform = defineBatchTransform;
+exports.defineBatchFilter = defineBatchFilter;
+exports.defineBatchReduce = defineBatchReduce;
+const tsyringe_1 = require("tsyringe");
+const uuid_1 = require("uuid");
+const worker_pool_1 = require("./worker-pool");
+const DEFAULT_WORKER_THRESHOLD = 10000;
+/**
+ * Service for managing parallel computation
+ */
+let ParallelComputeService = class ParallelComputeService {
+    constructor() {
+        this.pool = null;
+        this.metrics = {
+            totalTasks: 0,
+            syncTasks: 0,
+            parallelTasks: 0,
+            failedTasks: 0,
+            avgExecutionTime: 0,
+            estimatedTimeSaved: 0,
+            activeWorkers: 0,
+            peakWorkers: 0,
+        };
+        this.totalExecutionTime = 0;
+        this.isInitialized = false;
+        this.poolConfig = {};
+    }
+    /**
+     * Initialize the worker pool
+     * Must be called before using parallel execution
+     */
+    initialize(config = {}) {
+        if (this.isInitialized)
+            return;
+        this.poolConfig = config;
+        this.pool = new worker_pool_1.WorkerPool(config);
+        this.pool.on('taskCompleted', (data) => {
+            const { executionTime } = data;
+            this.updateMetrics(executionTime, 'parallel');
+        });
+        this.pool.on('workerSpawned', () => {
+            var _a;
+            const stats = (_a = this.pool) === null || _a === void 0 ? void 0 : _a.getStats();
+            if (stats) {
+                this.metrics.activeWorkers = stats.totalWorkers;
+                this.metrics.peakWorkers = Math.max(this.metrics.peakWorkers, stats.totalWorkers);
+            }
+        });
+        this.pool.on('workerExit', () => {
+            var _a;
+            const stats = (_a = this.pool) === null || _a === void 0 ? void 0 : _a.getStats();
+            if (stats) {
+                this.metrics.activeWorkers = stats.totalWorkers;
+            }
+        });
+        this.isInitialized = true;
+    }
+    /**
+     * Check if initialized
+     */
+    get initialized() {
+        return this.isInitialized;
+    }
+    /**
+     * Check if using native workers
+     */
+    get isNative() {
+        var _a, _b;
+        return (_b = (_a = this.pool) === null || _a === void 0 ? void 0 : _a.isNative) !== null && _b !== void 0 ? _b : false;
+    }
+    /**
+     * Shutdown the service and worker pool
+     */
+    async shutdown() {
+        if (this.pool) {
+            await this.pool.shutdown();
+            this.pool = null;
+        }
+        this.isInitialized = false;
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        return Object.assign({}, this.metrics);
+    }
+    /**
+     * Get worker pool statistics
+     */
+    getPoolStats() {
+        var _a, _b;
+        return (_b = (_a = this.pool) === null || _a === void 0 ? void 0 : _a.getStats()) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * Reset metrics
+     */
+    resetMetrics() {
+        var _a, _b;
+        this.metrics = {
+            totalTasks: 0,
+            syncTasks: 0,
+            parallelTasks: 0,
+            failedTasks: 0,
+            avgExecutionTime: 0,
+            estimatedTimeSaved: 0,
+            activeWorkers: (_b = (_a = this.pool) === null || _a === void 0 ? void 0 : _a.getStats().totalWorkers) !== null && _b !== void 0 ? _b : 0,
+            peakWorkers: 0,
+        };
+        this.totalExecutionTime = 0;
+    }
+    /**
+     * Execute a compute function with automatic mode selection
+     */
+    async run(options, input) {
+        var _a, _b, _c;
+        const cost = (_b = (_a = options.estimateCost) === null || _a === void 0 ? void 0 : _a.call(options, input)) !== null && _b !== void 0 ? _b : 0;
+        const threshold = (_c = options.workerThreshold) !== null && _c !== void 0 ? _c : DEFAULT_WORKER_THRESHOLD;
+        if (cost > threshold && this.pool) {
+            return this.parallel(options, input);
+        }
+        return this.sync(options, input);
+    }
+    /**
+     * Execute synchronously on main thread
+     */
+    sync(options, input) {
+        const startTime = performance.now();
+        try {
+            const result = options.compute(input);
+            const executionTime = performance.now() - startTime;
+            this.updateMetrics(executionTime, 'sync');
+            return {
+                result,
+                executionTime,
+                mode: 'sync',
+            };
+        }
+        catch (error) {
+            this.metrics.failedTasks++;
+            throw error;
+        }
+    }
+    /**
+     * Execute on worker (async with yielding in FiveM)
+     */
+    async parallel(options, input) {
+        if (!this.pool) {
+            // Fallback to sync if pool not initialized
+            return this.sync(options, input);
+        }
+        const startTime = performance.now();
+        try {
+            const message = {
+                id: (0, uuid_1.v4)(),
+                taskName: options.name,
+                functionBody: options.compute.toString(),
+                input,
+            };
+            const result = (await this.pool.execute(message));
+            const executionTime = performance.now() - startTime;
+            return {
+                result,
+                executionTime,
+                mode: 'parallel',
+            };
+        }
+        catch (error) {
+            this.metrics.failedTasks++;
+            throw error;
+        }
+    }
+    /**
+     * Execute distributed across multiple workers
+     */
+    async distributed(options, input, workerCount) {
+        var _a;
+        if (!options.chunker || !options.merger) {
+            throw new Error('Distributed execution requires chunker and merger functions');
+        }
+        if (!this.pool) {
+            // Fallback to sync if pool not initialized
+            return this.sync(options, input);
+        }
+        const startTime = performance.now();
+        const actualWorkerCount = (_a = workerCount !== null && workerCount !== void 0 ? workerCount : this.poolConfig.maxWorkers) !== null && _a !== void 0 ? _a : 4;
+        try {
+            const chunks = options.chunker(input, actualWorkerCount);
+            const results = await Promise.all(chunks.map(async (chunk) => {
+                const message = {
+                    id: (0, uuid_1.v4)(),
+                    taskName: options.name,
+                    functionBody: options.compute.toString(),
+                    input: chunk,
+                };
+                return this.pool.execute(message);
+            }));
+            const mergedResult = options.merger(results);
+            const executionTime = performance.now() - startTime;
+            this.updateMetrics(executionTime, 'distributed');
+            return {
+                result: mergedResult,
+                executionTime,
+                mode: 'distributed',
+                workerCount: chunks.length,
+            };
+        }
+        catch (error) {
+            this.metrics.failedTasks++;
+            throw error;
+        }
+    }
+    /**
+     * Update internal metrics
+     */
+    updateMetrics(executionTime, mode) {
+        this.metrics.totalTasks++;
+        this.totalExecutionTime += executionTime;
+        this.metrics.avgExecutionTime = this.totalExecutionTime / this.metrics.totalTasks;
+        if (mode === 'sync') {
+            this.metrics.syncTasks++;
+        }
+        else {
+            this.metrics.parallelTasks++;
+        }
+    }
+};
+exports.ParallelComputeService = ParallelComputeService;
+exports.ParallelComputeService = ParallelComputeService = __decorate([
+    (0, tsyringe_1.injectable)()
+], ParallelComputeService);
+// ─────────────────────────────────────────────────────────────────────────────
+// Standalone Functions (no DI required)
+// ─────────────────────────────────────────────────────────────────────────────
+let globalService = null;
+/**
+ * Get or create the global ParallelCompute service instance
+ */
+function getParallelComputeService() {
+    if (!globalService) {
+        globalService = new ParallelComputeService();
+    }
+    return globalService;
+}
+/**
+ * Initialize the global ParallelCompute service
+ */
+function initParallelCompute(config = {}) {
+    const service = getParallelComputeService();
+    service.initialize(config);
+}
+/**
+ * Shutdown the global ParallelCompute service
+ */
+async function shutdownParallelCompute() {
+    if (globalService) {
+        await globalService.shutdown();
+        globalService = null;
+    }
+}
+/**
+ * Define a parallel task with the given options
+ * Returns a task object with run, sync, parallel, and distributed methods
+ */
+function defineTask(options) {
+    const service = getParallelComputeService();
+    return {
+        name: options.name,
+        options,
+        async run(input) {
+            const result = await service.run(options, input);
+            return result.result;
+        },
+        sync(input) {
+            const result = service.sync(options, input);
+            return result.result;
+        },
+        async parallel(input) {
+            const result = await service.parallel(options, input);
+            return result.result;
+        },
+        async distributed(input, workerCount) {
+            const result = await service.distributed(options, input, workerCount);
+            return result.result;
+        },
+    };
+}
+/**
+ * Built-in task: Filter entities by distance from a position
+ */
+exports.filterByDistance = defineTask({
+    name: 'filterByDistance',
+    estimateCost: (input) => input.entities.length,
+    workerThreshold: 1000,
+    compute: (input) => {
+        const { entities, position, radius } = input;
+        const radiusSquared = radius * radius;
+        return entities.filter((entity) => {
+            const dx = entity.x - position.x;
+            const dy = entity.y - position.y;
+            const dz = entity.z - position.z;
+            return dx * dx + dy * dy + dz * dz <= radiusSquared;
+        });
+    },
+    chunker: (input, workerCount) => {
+        const { entities, position, radius } = input;
+        const chunkSize = Math.ceil(entities.length / workerCount);
+        const chunks = [];
+        for (let i = 0; i < entities.length; i += chunkSize) {
+            chunks.push({
+                entities: entities.slice(i, i + chunkSize),
+                position,
+                radius,
+            });
+        }
+        return chunks;
+    },
+    merger: (results) => [].concat(...results),
+});
+/**
+ * Built-in task: Sort entities by distance from a position
+ */
+exports.sortByDistance = defineTask({
+    name: 'sortByDistance',
+    estimateCost: (input) => input.entities.length * Math.log(input.entities.length),
+    workerThreshold: 500,
+    compute: (input) => {
+        const { entities, position } = input;
+        return [...entities].sort((a, b) => {
+            const dxA = a.x - position.x;
+            const dyA = a.y - position.y;
+            const dzA = a.z - position.z;
+            const distA = dxA * dxA + dyA * dyA + dzA * dzA;
+            const dxB = b.x - position.x;
+            const dyB = b.y - position.y;
+            const dzB = b.z - position.z;
+            const distB = dxB * dxB + dyB * dyB + dzB * dzB;
+            return distA - distB;
+        });
+    },
+});
+/**
+ * Built-in task: Find closest entity to a position
+ */
+exports.findClosest = defineTask({
+    name: 'findClosest',
+    estimateCost: (input) => input.entities.length,
+    workerThreshold: 5000,
+    compute: (input) => {
+        const { entities, position } = input;
+        if (entities.length === 0)
+            return null;
+        let closest = entities[0];
+        let minDistSquared = Infinity;
+        for (const entity of entities) {
+            const dx = entity.x - position.x;
+            const dy = entity.y - position.y;
+            const dz = entity.z - position.z;
+            const distSquared = dx * dx + dy * dy + dz * dz;
+            if (distSquared < minDistSquared) {
+                minDistSquared = distSquared;
+                closest = entity;
+            }
+        }
+        return closest;
+    },
+});
+/**
+ * Built-in task: Batch transform items
+ */
+function defineBatchTransform(name, transform, threshold = 1000) {
+    return defineTask({
+        name,
+        estimateCost: (input) => input.length,
+        workerThreshold: threshold,
+        compute: (input) => input.map(transform),
+        chunker: (input, workerCount) => {
+            const chunkSize = Math.ceil(input.length / workerCount);
+            const chunks = [];
+            for (let i = 0; i < input.length; i += chunkSize) {
+                chunks.push(input.slice(i, i + chunkSize));
+            }
+            return chunks;
+        },
+        merger: (results) => [].concat(...results),
+    });
+}
+/**
+ * Built-in task: Batch filter items
+ */
+function defineBatchFilter(name, predicate, threshold = 1000) {
+    return defineTask({
+        name,
+        estimateCost: (input) => input.length,
+        workerThreshold: threshold,
+        compute: (input) => input.filter(predicate),
+        chunker: (input, workerCount) => {
+            const chunkSize = Math.ceil(input.length / workerCount);
+            const chunks = [];
+            for (let i = 0; i < input.length; i += chunkSize) {
+                chunks.push(input.slice(i, i + chunkSize));
+            }
+            return chunks;
+        },
+        merger: (results) => [].concat(...results),
+    });
+}
+/**
+ * Built-in task: Batch reduce items
+ */
+function defineBatchReduce(name, reducer, initial, merger, threshold = 1000) {
+    return defineTask({
+        name,
+        estimateCost: (input) => input.length,
+        workerThreshold: threshold,
+        compute: (input) => input.reduce(reducer, initial),
+        chunker: (input, workerCount) => {
+            const chunkSize = Math.ceil(input.length / workerCount);
+            const chunks = [];
+            for (let i = 0; i < input.length; i += chunkSize) {
+                chunks.push(input.slice(i, i + chunkSize));
+            }
+            return chunks;
+        },
+        merger,
+    });
+}

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 });