@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/apis/parallel-compute.api.d.ts

@@ -0,0 +1,118 @@
+import { Vector3 } from '../../../kernel';
+import { ParallelComputeMetrics, ParallelTask, ParallelTaskOptions, TaskResult, WorkerPoolConfig } from '../types/parallel.types';
+/**
+ * Service for managing parallel computation
+ */
+export declare class ParallelCompute {
+    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(): ParallelCompute;
+/**
+ * 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>;
+/**
+ * Built-in task: Filter entities by distance from a position
+ */
+export declare const filterByDistance: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+    radius: number;
+}, Vector3[]>;
+/**
+ * Built-in task: Sort entities by distance from a position
+ */
+export declare const sortByDistance: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+}, Vector3[]>;
+/**
+ * Built-in task: Find closest entity to a position
+ */
+export declare const findClosest: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+}, Vector3 | 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/runtime/server/apis/parallel-compute.api.js

@@ -0,0 +1,423 @@
+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;
+};
+import { injectable } from 'tsyringe';
+import { v4 as uuid } from 'uuid';
+import { WorkerPool } from '../services/parallel/worker-pool';
+const DEFAULT_WORKER_THRESHOLD = 10000;
+/**
+ * Service for managing parallel computation
+ */
+let ParallelCompute = class ParallelCompute {
+    pool = null;
+    metrics = {
+        totalTasks: 0,
+        syncTasks: 0,
+        parallelTasks: 0,
+        failedTasks: 0,
+        avgExecutionTime: 0,
+        estimatedTimeSaved: 0,
+        activeWorkers: 0,
+        peakWorkers: 0,
+    };
+    totalExecutionTime = 0;
+    isInitialized = false;
+    poolConfig = {};
+    /**
+     * Initialize the worker pool
+     * Must be called before using parallel execution
+     */
+    initialize(config = {}) {
+        if (this.isInitialized)
+            return;
+        this.poolConfig = config;
+        this.pool = new WorkerPool(config);
+        this.pool.on('taskCompleted', (data) => {
+            const { executionTime } = data;
+            this.updateMetrics(executionTime, 'parallel');
+        });
+        this.pool.on('workerSpawned', () => {
+            const stats = this.pool?.getStats();
+            if (stats) {
+                this.metrics.activeWorkers = stats.totalWorkers;
+                this.metrics.peakWorkers = Math.max(this.metrics.peakWorkers, stats.totalWorkers);
+            }
+        });
+        this.pool.on('workerExit', () => {
+            const stats = this.pool?.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() {
+        return this.pool?.isNative ?? 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 { ...this.metrics };
+    }
+    /**
+     * Get worker pool statistics
+     */
+    getPoolStats() {
+        return this.pool?.getStats() ?? null;
+    }
+    /**
+     * Reset metrics
+     */
+    resetMetrics() {
+        this.metrics = {
+            totalTasks: 0,
+            syncTasks: 0,
+            parallelTasks: 0,
+            failedTasks: 0,
+            avgExecutionTime: 0,
+            estimatedTimeSaved: 0,
+            activeWorkers: this.pool?.getStats().totalWorkers ?? 0,
+            peakWorkers: 0,
+        };
+        this.totalExecutionTime = 0;
+    }
+    /**
+     * Execute a compute function with automatic mode selection
+     */
+    async run(options, input) {
+        const cost = options.estimateCost?.(input) ?? 0;
+        const threshold = options.workerThreshold ?? 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: uuid(),
+                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) {
+        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 = workerCount ?? this.poolConfig.maxWorkers ?? 4;
+        try {
+            const chunks = options.chunker(input, actualWorkerCount);
+            const results = await Promise.all(chunks.map(async (chunk) => {
+                const message = {
+                    id: uuid(),
+                    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++;
+        }
+    }
+};
+ParallelCompute = __decorate([
+    injectable()
+], ParallelCompute);
+export { ParallelCompute };
+// ─────────────────────────────────────────────────────────────────────────────
+// Standalone Functions (no DI required)
+// ─────────────────────────────────────────────────────────────────────────────
+let globalService = null;
+/**
+ * Get or create the global ParallelCompute service instance
+ */
+export function getParallelComputeService() {
+    if (!globalService) {
+        globalService = new ParallelCompute();
+    }
+    return globalService;
+}
+/**
+ * Initialize the global ParallelCompute service
+ */
+export function initParallelCompute(config = {}) {
+    const service = getParallelComputeService();
+    service.initialize(config);
+}
+/**
+ * Shutdown the global ParallelCompute service
+ */
+export 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
+ */
+export 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 Tasks
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Built-in task: Filter entities by distance from a position
+ */
+export const 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
+ */
+export const 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
+ */
+export const 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
+ */
+export 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
+ */
+export 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
+ */
+export 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/runtime/server/apis/vehicle-modification.api.d.ts

@@ -0,0 +1,94 @@
+import { VehicleModificationOptions, VehicleMods } from '../types/vehicle.types';
+import { Vehicles } from './vehicles.api';
+/**
+ * Service for handling vehicle modifications with validation.
+ *
+ * This service is separated from VehicleService to maintain single responsibility.
+ * All modifications are validated server-side before being applied.
+ *
+ * Security features:
+ * - Ownership validation
+ * - Proximity checks
+ * - Modification limits
+ * - Audit logging
+ */
+export declare class VehicleModification {
+    private readonly vehicleService;
+    constructor(vehicleService: Vehicles);
+    /**
+     * Applies modifications to a vehicle with validation.
+     *
+     * @param options - Modification options
+     * @returns Success status
+     */
+    applyModifications(options: VehicleModificationOptions): boolean;
+    /**
+     * Sets vehicle colors with validation.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param primaryColor - Primary color ID
+     * @param secondaryColor - Secondary color ID
+     * @param requestedBy - Client ID requesting the change
+     * @returns Success status
+     */
+    setColors(networkId: number, primaryColor: number, secondaryColor: number, requestedBy?: number): boolean;
+    /**
+     * Sets vehicle livery with validation.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param livery - Livery index
+     * @param requestedBy - Client ID requesting the change
+     * @returns Success status
+     */
+    setLivery(networkId: number, livery: number, requestedBy?: number): boolean;
+    /**
+     * Toggles vehicle turbo with validation.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param enabled - Whether turbo should be enabled
+     * @param requestedBy - Client ID requesting the change
+     * @returns Success status
+     */
+    setTurbo(networkId: number, enabled: boolean, requestedBy?: number): boolean;
+    /**
+     * Sets vehicle window tint with validation.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param tint - Tint level (0-6)
+     * @param requestedBy - Client ID requesting the change
+     * @returns Success status
+     */
+    setWindowTint(networkId: number, tint: number, requestedBy?: number): boolean;
+    /**
+     * Sets vehicle neon lights with validation.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param enabled - Array of [left, right, front, back] enabled states
+     * @param color - RGB color array
+     * @param requestedBy - Client ID requesting the change
+     * @returns Success status
+     */
+    setNeon(networkId: number, enabled: [boolean, boolean, boolean, boolean], color?: [number, number, number], requestedBy?: number): boolean;
+    /**
+     * Resets all modifications on a vehicle.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @param requestedBy - Client ID requesting the reset
+     * @returns Success status
+     */
+    resetModifications(networkId: number, requestedBy?: number): boolean;
+    /**
+     * Gets the current modifications of a vehicle.
+     *
+     * @param networkId - Network ID of the vehicle
+     * @returns Vehicle mods or undefined
+     */
+    getModifications(networkId: number): VehicleMods | undefined;
+    /**
+     * Validates modification values to prevent exploits.
+     *
+     * @param mods - Modifications to validate
+     * @returns Validated modifications
+     */
+    private validateMods;
+}