@open-core/framework 1.0.1-beta.1

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

@@ -0,0 +1,49 @@
+/**
+ * ParallelCompute Module
+ *
+ * Provides parallel computation capabilities using worker threads.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   initParallelCompute,
+ *   defineTask,
+ *   filterByDistance,
+ * } from '@open-core/framework/server'
+ *
+ * // Initialize the worker pool (call once at startup)
+ * initParallelCompute({ maxWorkers: 4 })
+ *
+ * // Use built-in tasks
+ * const nearby = await filterByDistance.run({
+ *   entities: allEntities,
+ *   position: player.coords,
+ *   radius: 100,
+ * })
+ *
+ * // Define custom tasks
+ * const processPlayers = defineTask({
+ *   name: 'processPlayers',
+ *   estimateCost: (input) => input.length * 10,
+ *   workerThreshold: 500,
+ *   compute: (players) => players.map(p => ({
+ *     ...p,
+ *     processed: true,
+ *   })),
+ * })
+ *
+ * // Run with automatic mode selection
+ * const result = await processPlayers.run(players)
+ *
+ * // Force sync execution
+ * const resultSync = processPlayers.sync(players)
+ *
+ * // Force parallel execution
+ * const resultParallel = await processPlayers.parallel(players)
+ * ```
+ */
+export type { ExecutionMode, WorkerPoolConfig, ParallelTaskOptions, ParallelTask, ParallelComputeMetrics, TaskResult, WorkerInfo, WorkerStatus, } from './types';
+export { ParallelComputeService } from './parallel-compute.service';
+export { getParallelComputeService, initParallelCompute, shutdownParallelCompute, defineTask, } from './parallel-compute.service';
+export { filterByDistance, sortByDistance, findClosest, defineBatchTransform, defineBatchFilter, defineBatchReduce, type Vector3Like, } from './parallel-compute.service';
+export { WorkerPool } from './worker-pool';

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

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * ParallelCompute Module
+ *
+ * Provides parallel computation capabilities using worker threads.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   initParallelCompute,
+ *   defineTask,
+ *   filterByDistance,
+ * } from '@open-core/framework/server'
+ *
+ * // Initialize the worker pool (call once at startup)
+ * initParallelCompute({ maxWorkers: 4 })
+ *
+ * // Use built-in tasks
+ * const nearby = await filterByDistance.run({
+ *   entities: allEntities,
+ *   position: player.coords,
+ *   radius: 100,
+ * })
+ *
+ * // Define custom tasks
+ * const processPlayers = defineTask({
+ *   name: 'processPlayers',
+ *   estimateCost: (input) => input.length * 10,
+ *   workerThreshold: 500,
+ *   compute: (players) => players.map(p => ({
+ *     ...p,
+ *     processed: true,
+ *   })),
+ * })
+ *
+ * // Run with automatic mode selection
+ * const result = await processPlayers.run(players)
+ *
+ * // Force sync execution
+ * const resultSync = processPlayers.sync(players)
+ *
+ * // Force parallel execution
+ * const resultParallel = await processPlayers.parallel(players)
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = exports.defineBatchReduce = exports.defineBatchFilter = exports.defineBatchTransform = exports.findClosest = exports.sortByDistance = exports.filterByDistance = exports.defineTask = exports.shutdownParallelCompute = exports.initParallelCompute = exports.getParallelComputeService = exports.ParallelComputeService = void 0;
+// Service
+var parallel_compute_service_1 = require("./parallel-compute.service");
+Object.defineProperty(exports, "ParallelComputeService", { enumerable: true, get: function () { return parallel_compute_service_1.ParallelComputeService; } });
+// Standalone functions
+var parallel_compute_service_2 = require("./parallel-compute.service");
+Object.defineProperty(exports, "getParallelComputeService", { enumerable: true, get: function () { return parallel_compute_service_2.getParallelComputeService; } });
+Object.defineProperty(exports, "initParallelCompute", { enumerable: true, get: function () { return parallel_compute_service_2.initParallelCompute; } });
+Object.defineProperty(exports, "shutdownParallelCompute", { enumerable: true, get: function () { return parallel_compute_service_2.shutdownParallelCompute; } });
+Object.defineProperty(exports, "defineTask", { enumerable: true, get: function () { return parallel_compute_service_2.defineTask; } });
+// Built-in tasks
+var parallel_compute_service_3 = require("./parallel-compute.service");
+Object.defineProperty(exports, "filterByDistance", { enumerable: true, get: function () { return parallel_compute_service_3.filterByDistance; } });
+Object.defineProperty(exports, "sortByDistance", { enumerable: true, get: function () { return parallel_compute_service_3.sortByDistance; } });
+Object.defineProperty(exports, "findClosest", { enumerable: true, get: function () { return parallel_compute_service_3.findClosest; } });
+Object.defineProperty(exports, "defineBatchTransform", { enumerable: true, get: function () { return parallel_compute_service_3.defineBatchTransform; } });
+Object.defineProperty(exports, "defineBatchFilter", { enumerable: true, get: function () { return parallel_compute_service_3.defineBatchFilter; } });
+Object.defineProperty(exports, "defineBatchReduce", { enumerable: true, get: function () { return parallel_compute_service_3.defineBatchReduce; } });
+// Worker pool (for advanced usage)
+var worker_pool_1 = require("./worker-pool");
+Object.defineProperty(exports, "WorkerPool", { enumerable: true, get: function () { return worker_pool_1.WorkerPool; } });

package/dist/server/services/parallel/parallel-compute.service.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+import type { ParallelTaskOptions, ParallelTask, WorkerPoolConfig, ParallelComputeMetrics, TaskResult } from './types';
+/**
+ * Service for managing parallel computation
+ */
+export declare class ParallelComputeService {
+    private pool;
+    private metrics;
+    private totalExecutionTime;
+    private isInitialized;
+    private poolConfig;
+    /**
+     * Initialize the worker pool
+     * Must be called before using parallel execution
+     */
+    initialize(config?: Partial<WorkerPoolConfig>): void;
+    /**
+     * Check if initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Check if using native workers
+     */
+    get isNative(): boolean;
+    /**
+     * Shutdown the service and worker pool
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): ParallelComputeMetrics;
+    /**
+     * Get worker pool statistics
+     */
+    getPoolStats(): {
+        totalWorkers: number;
+        idleWorkers: number;
+        busyWorkers: number;
+        queuedTasks: number;
+        isNative: boolean;
+    } | null;
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Execute a compute function with automatic mode selection
+     */
+    run<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): Promise<TaskResult<TOutput>>;
+    /**
+     * Execute synchronously on main thread
+     */
+    sync<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): TaskResult<TOutput>;
+    /**
+     * Execute on worker (async with yielding in FiveM)
+     */
+    parallel<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): Promise<TaskResult<TOutput>>;
+    /**
+     * Execute distributed across multiple workers
+     */
+    distributed<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput, workerCount?: number): Promise<TaskResult<TOutput>>;
+    /**
+     * Update internal metrics
+     */
+    private updateMetrics;
+}
+/**
+ * Get or create the global ParallelCompute service instance
+ */
+export declare function getParallelComputeService(): ParallelComputeService;
+/**
+ * Initialize the global ParallelCompute service
+ */
+export declare function initParallelCompute(config?: Partial<WorkerPoolConfig>): void;
+/**
+ * Shutdown the global ParallelCompute service
+ */
+export declare function shutdownParallelCompute(): Promise<void>;
+/**
+ * Define a parallel task with the given options
+ * Returns a task object with run, sync, parallel, and distributed methods
+ */
+export declare function defineTask<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>): ParallelTask<TInput, TOutput>;
+export interface Vector3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Built-in task: Filter entities by distance from a position
+ */
+export declare const filterByDistance: ParallelTask<{
+    entities: Vector3Like[];
+    position: Vector3Like;
+    radius: number;
+}, Vector3Like[]>;
+/**
+ * Built-in task: Sort entities by distance from a position
+ */
+export declare const sortByDistance: ParallelTask<{
+    entities: Vector3Like[];
+    position: Vector3Like;
+}, Vector3Like[]>;
+/**
+ * Built-in task: Find closest entity to a position
+ */
+export declare const findClosest: ParallelTask<{
+    entities: Vector3Like[];
+    position: Vector3Like;
+}, Vector3Like | null>;
+/**
+ * Built-in task: Batch transform items
+ */
+export declare function defineBatchTransform<T, R>(name: string, transform: (item: T) => R, threshold?: number): ParallelTask<T[], R[]>;
+/**
+ * Built-in task: Batch filter items
+ */
+export declare function defineBatchFilter<T>(name: string, predicate: (item: T) => boolean, threshold?: number): ParallelTask<T[], T[]>;
+/**
+ * Built-in task: Batch reduce items
+ */
+export declare function defineBatchReduce<T, R>(name: string, reducer: (acc: R, item: T) => R, initial: R, merger: (results: R[]) => R, threshold?: number): ParallelTask<T[], R>;

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