@open-core/framework 0.2.2-beta.1 → 0.2.4

package/README.md

@@ -1,217 +1,217 @@
-# OpenCore Framework (v0.2.2-beta.1)
-
-OpenCore is a TypeScript multiplayer runtime framework targeting FiveM via an adapter.
-
-It is not a gamemode or RP framework. It provides:
-
-- A stable execution model (server and client)
-- Dependency Injection and metadata-driven wiring
-- An event/command system
-- Security primitives (validation, access control, rate limiting)
-
-License: MPL-2.0
-
-## Scope
-
-This package (`@open-core/framework`) contains transversal infrastructure only.
-
-- Controllers, services, decorators, and processors
-- Session/lifecycle primitives and contracts
-- Adapters and capability registration
-
-Gameplay logic must live in separate resources/modules.
-
-## Installation
-
-```bash
-pnpm add @open-core/framework reflect-metadata tsyringe zod uuid
-```
-
-This framework uses TypeScript decorators. Ensure your project has decorators enabled.
-
-## Imports and entry points
-
-The package exposes subpath entry points:
-
-- `@open-core/framework` (root)
-- `@open-core/framework/server`
-- `@open-core/framework/client`
-- `@open-core/framework/shared`
-- `@open-core/framework/utils`
-
-Most projects will import the `Server`/`Client` namespaces:
-
-```ts
-import { Server } from '@open-core/framework'
-```
-
-## Architecture
-
-OpenCore follows a Ports & Adapters (Hexagonal) architecture.
-
-- Kernel (`src/kernel`): engine-agnostic infrastructure (DI, logger, metadata scanning)
-- Runtime (`src/runtime`): multiplayer execution model (controllers, processors, security, lifecycle)
-- Adapters (`src/adapters`): platform integration (FiveM, Node testing)
-
-The runtime never auto-detects the platform. Adapters are selected explicitly at bootstrap time.
-
-## Operating modes
-
-Each instance runs in exactly one mode configured via `Server.init()`:
-
-- `CORE`: authoritative runtime. Typically provides identity/auth/players via exports.
-- `RESOURCE`: a normal FiveM resource using CORE as provider for some features.
-- `STANDALONE`: a self-contained runtime (useful for tooling, simulations, or small servers).
-
-## Server bootstrap
-
-Initialize the server runtime:
-
-```ts
-import { Server } from '@open-core/framework/server'
-
-await Server.init({
-  mode: 'STANDALONE',
-  features: {
-    commands: { enabled: true },
-    netEvents: { enabled: true },
-  },
-})
-```
-
-Some features require providers (depending on your mode and configuration). Configure them before calling `init()`:
-
-```ts
-import { Server } from '@open-core/framework/server'
-
-Server.setPrincipalProvider(MyPrincipalProvider)
-Server.setAuthProvider(MyAuthProvider)
-Server.setSecurityHandler(MySecurityHandler)
-Server.setPersistenceProvider(MyPlayerPersistence)
-Server.setNetEventSecurityObserver(MyNetEventSecurityObserver)
-```
-
-## Controllers and decorators
-
-OpenCore uses a decorator + processor pattern.
-
-Decorators store metadata with `Reflect.defineMetadata()`. During bootstrap, the `MetadataScanner` reads metadata and processors register handlers.
-
-### Commands
-
-```ts
-import { Server } from '@open-core/framework/server'
-import { z } from 'zod'
-
-const TransferSchema = z.tuple([z.coerce.number().int().positive(), z.coerce.number().min(1)])
-
-@Server.Controller()
-export class BankController {
-  @Server.Command({
-    command: 'transfer',
-    usage: '/transfer <id> <amount>',
-    schema: TransferSchema,
-  })
-  @Server.Guard({ rank: 1 })
-  @Server.Throttle(1, 2000)
-  async transfer(player: Server.Player, args: z.infer<typeof TransferSchema>) {
-    const [targetId, amount] = args
-    player.emit('chat:message', `transfer -> ${targetId} (${amount})`)
-  }
-}
-```
-
-### Network events
-
-`@OnNet()` handlers always receive `Player` as the first parameter.
-
-```ts
-import { Server } from '@open-core/framework/server'
-import { z } from 'zod'
-
-const PayloadSchema = z.object({ action: z.string(), amount: z.number().int().positive() })
-
-@Server.Controller()
-export class ExampleNetController {
-  @Server.OnNet('bank:action', { schema: PayloadSchema })
-  async onBankAction(player: Server.Player, payload: z.infer<typeof PayloadSchema>) {
-    player.emit('chat:message', `action=${payload.action} amount=${payload.amount}`)
-  }
-}
-```
-
-### Security decorators
-
-- `@Guard({ rank })` or `@Guard({ permission })`
-- `@Throttle(limit, windowMs)`
-- `@RequiresState({ missing: [...] })`
-
-## Testing
-
-Tests run with Vitest.
-
-```bash
-pnpm test
-pnpm test:unit
-pnpm test:integration
-pnpm test:coverage
-```
-
-Note: `pnpm test` does not run benchmarks.
-
-## Benchmarks
-
-There are two benchmark suites:
-
-- Core benchmarks (Tinybench)
-- Load benchmarks (Vitest project `benchmark`)
-
-```bash
-pnpm bench:core
-pnpm bench:load
-pnpm bench:all
-```
-
-### Snapshot (latest local run)
-
-These values are a small extract from a recent local run (Dec 22, 2025). Results vary by machine.
-
-- **Core**
-  - Decorators - Define metadata (Command): `~5.72M ops/sec` (mean `0.17μs`)
-  - EventBus - Multiple event types: `~2.01M ops/sec` (mean `0.50μs`)
-  - Dependency Injection (simple resolve): `~1.7M ops/sec`
-- **Load**
-  - Net Events - Simple (10 players): `~28.85K ops/sec` (p95 `0.25ms`)
-  - Net Events - Concurrent (500 players): `~1.18M ops/sec` (p95 `0.40ms`)
-  - Commands (validated, ~500 players): `~14M ops/sec`
-
-Full reports and methodology are available in benchmark/README.md.
-
-### Reports
-
-Benchmark reports are generated under `benchmark/reports/`.
-
-- `pnpm bench:all` generates aggregated reports (text/json/html)
-- Load metrics used by load benchmarks are persisted in `benchmark/reports/.load-metrics.json`
-
-For details about the benchmark system, see `benchmark/README.md`.
-
-## Development scripts
-
-```bash
-pnpm build
-pnpm watch
-pnpm lint
-pnpm lint:fix
-pnpm format
-```
-
-## Ecosystem
-
-OpenCore is designed to be extended via separate packages/resources.
-
-- `@open-core/identity`: identity and permission system
-
-## License
-
-MPL-2.0. See `LICENSE`.
+# OpenCore Framework (v0.2.4) Open Stable beta
+
+OpenCore is a TypeScript multiplayer runtime framework targeting FiveM via an adapter.
+
+It is not a gamemode or RP framework. It provides:
+
+- A stable execution model (server and client)
+- Dependency Injection and metadata-driven wiring
+- An event/command system
+- Security primitives (validation, access control, rate limiting)
+
+License: MPL-2.0
+
+## Scope
+
+This package (`@open-core/framework`) contains transversal infrastructure only.
+
+- Controllers, services, decorators, and processors
+- Session/lifecycle primitives and contracts
+- Adapters and capability registration
+
+Gameplay logic must live in separate resources/modules.
+
+## Installation
+
+```bash
+pnpm add @open-core/framework reflect-metadata tsyringe zod uuid
+```
+
+This framework uses TypeScript decorators. Ensure your project has decorators enabled.
+
+## Imports and entry points
+
+The package exposes subpath entry points:
+
+- `@open-core/framework` (root)
+- `@open-core/framework/server`
+- `@open-core/framework/client`
+- `@open-core/framework/shared`
+- `@open-core/framework/utils`
+
+Most projects will import the `Server`/`Client` namespaces:
+
+```ts
+import { Server } from '@open-core/framework'
+```
+
+## Architecture
+
+OpenCore follows a Ports & Adapters (Hexagonal) architecture.
+
+- Kernel (`src/kernel`): engine-agnostic infrastructure (DI, logger, metadata scanning)
+- Runtime (`src/runtime`): multiplayer execution model (controllers, processors, security, lifecycle)
+- Adapters (`src/adapters`): platform integration (FiveM, Node testing)
+
+The runtime never auto-detects the platform. Adapters are selected explicitly at bootstrap time.
+
+## Operating modes
+
+Each instance runs in exactly one mode configured via `Server.init()`:
+
+- `CORE`: authoritative runtime. Typically provides identity/auth/players via exports.
+- `RESOURCE`: a normal FiveM resource using CORE as provider for some features.
+- `STANDALONE`: a self-contained runtime (useful for tooling, simulations, or small servers).
+
+## Server bootstrap
+
+Initialize the server runtime:
+
+```ts
+import { Server } from '@open-core/framework/server'
+
+await Server.init({
+  mode: 'STANDALONE',
+  features: {
+    commands: { enabled: true },
+    netEvents: { enabled: true },
+  },
+})
+```
+
+Some features require providers (depending on your mode and configuration). Configure them before calling `init()`:
+
+```ts
+import { Server } from '@open-core/framework/server'
+
+Server.setPrincipalProvider(MyPrincipalProvider)
+Server.setAuthProvider(MyAuthProvider)
+Server.setSecurityHandler(MySecurityHandler)
+Server.setPersistenceProvider(MyPlayerPersistence)
+Server.setNetEventSecurityObserver(MyNetEventSecurityObserver)
+```
+
+## Controllers and decorators
+
+OpenCore uses a decorator + processor pattern.
+
+Decorators store metadata with `Reflect.defineMetadata()`. During bootstrap, the `MetadataScanner` reads metadata and processors register handlers.
+
+### Commands
+
+```ts
+import { Server } from '@open-core/framework/server'
+import { z } from 'zod'
+
+const TransferSchema = z.tuple([z.coerce.number().int().positive(), z.coerce.number().min(1)])
+
+@Server.Controller()
+export class BankController {
+  @Server.Command({
+    command: 'transfer',
+    usage: '/transfer <id> <amount>',
+    schema: TransferSchema,
+  })
+  @Server.Guard({ rank: 1 })
+  @Server.Throttle(1, 2000)
+  async transfer(player: Server.Player, args: z.infer<typeof TransferSchema>) {
+    const [targetId, amount] = args
+    player.emit('chat:message', `transfer -> ${targetId} (${amount})`)
+  }
+}
+```
+
+### Network events
+
+`@OnNet()` handlers always receive `Player` as the first parameter.
+
+```ts
+import { Server } from '@open-core/framework/server'
+import { z } from 'zod'
+
+const PayloadSchema = z.object({ action: z.string(), amount: z.number().int().positive() })
+
+@Server.Controller()
+export class ExampleNetController {
+  @Server.OnNet('bank:action', { schema: PayloadSchema })
+  async onBankAction(player: Server.Player, payload: z.infer<typeof PayloadSchema>) {
+    player.emit('chat:message', `action=${payload.action} amount=${payload.amount}`)
+  }
+}
+```
+
+### Security decorators
+
+- `@Guard({ rank })` or `@Guard({ permission })`
+- `@Throttle(limit, windowMs)`
+- `@RequiresState({ missing: [...] })`
+
+## Testing
+
+Tests run with Vitest.
+
+```bash
+pnpm test
+pnpm test:unit
+pnpm test:integration
+pnpm test:coverage
+```
+
+Note: `pnpm test` does not run benchmarks.
+
+## Benchmarks
+
+There are two benchmark suites:
+
+- Core benchmarks (Tinybench)
+- Load benchmarks (Vitest project `benchmark`)
+
+```bash
+pnpm bench:core
+pnpm bench:load
+pnpm bench:all
+```
+
+### Snapshot (latest local run)
+
+These values are a small extract from a recent local run (Dec 22, 2025). Results vary by machine.
+
+- **Core**
+  - Decorators - Define metadata (Command): `~5.72M ops/sec` (mean `0.17μs`)
+  - EventBus - Multiple event types: `~2.01M ops/sec` (mean `0.50μs`)
+  - Dependency Injection (simple resolve): `~1.7M ops/sec`
+- **Load**
+  - Net Events - Simple (10 players): `~28.85K ops/sec` (p95 `0.25ms`)
+  - Net Events - Concurrent (500 players): `~1.18M ops/sec` (p95 `0.40ms`)
+  - Commands (validated, ~500 players): `~14M ops/sec`
+
+Full reports and methodology are available in benchmark/README.md.
+
+### Reports
+
+Benchmark reports are generated under `benchmark/reports/`.
+
+- `pnpm bench:all` generates aggregated reports (text/json/html)
+- Load metrics used by load benchmarks are persisted in `benchmark/reports/.load-metrics.json`
+
+For details about the benchmark system, see `benchmark/README.md`.
+
+## Development scripts
+
+```bash
+pnpm build
+pnpm watch
+pnpm lint
+pnpm lint:fix
+pnpm format
+```
+
+## Ecosystem
+
+OpenCore is designed to be extended via separate packages/resources.
+
+- `@open-core/identity`: identity and permission system
+
+## License
+
+MPL-2.0. See `LICENSE`.

package/dist/adapters/node/node-entity-server.js

@@ -68,6 +68,9 @@ let NodeEntityServer = class NodeEntityServer extends IEntityServer_1.IEntitySer
             this.stateBags.set(handle, new Map());
         }
         const bag = this.stateBags.get(handle);
+        if (!bag) {
+            throw new Error(`[OpenCore] NodeEntityServer state bag missing for handle ${handle}`);
+        }
         return {
             set: (key, value) => {
                 bag.set(key, value);

package/dist/adapters/node/node-exports.d.ts

@@ -5,7 +5,7 @@ import { IExports } from '../contracts/IExports';
  */
 export declare class NodeExports implements IExports {
     private exports;
-    register(exportName: string, handler: Function): void;
+    register(exportName: string, handler: (...args: any[]) => any): void;
     getResource(resourceName: string): any;
     /**
      * Get all registered exports as an object
@@ -18,7 +18,7 @@ export declare class NodeExports implements IExports {
     /**
      * Utility method for testing: get a specific export
      */
-    getExport(exportName: string): Function | undefined;
+    getExport(exportName: string): ((...args: any[]) => any) | undefined;
     /**
      * Utility method for testing: clear all exports
      */

package/dist/kernel/utils/vector3.d.ts

@@ -4,6 +4,7 @@ export type Vector3 = {
     z: number;
 };
 export declare class Vec3 {
+    private constructor();
     static create(x: number, y: number, z: number): Vector3;
     static clone(v: Vector3): Vector3;
     static add(a: Vector3, b: Vector3): Vector3;

package/dist/kernel/utils/vector3.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Vec3 = void 0;
 class Vec3 {
+    constructor() { }
     static create(x, y, z) {
         return { x, y, z };
     }

package/dist/runtime/client/services/appearance.service.js

@@ -129,6 +129,10 @@ let AppearanceService = class AppearanceService {
             components: {},
             props: {},
         };
+        if (!appearance.components)
+            appearance.components = {};
+        if (!appearance.props)
+            appearance.props = {};
         // Components (0-11)
         for (let i = 0; i <= 11; i++) {
             const drawable = this.pedAdapter.getDrawableVariation(ped, i);

package/dist/runtime/server/bootstrap.js

@@ -37,8 +37,8 @@ exports.initServer = initServer;
 const register_capabilities_1 = require("../../adapters/register-capabilities");
 const index_1 = require("../../kernel/di/index");
 const logger_1 = require("../../kernel/shared/logger");
-const index_2 = require("./contracts/index");
 const bootstrap_validation_1 = require("./bootstrap.validation");
+const index_2 = require("./contracts/index");
 const controller_1 = require("./decorators/controller");
 const runtime_1 = require("./runtime");
 const services_register_1 = require("./services/services.register");

package/dist/runtime/server/bootstrap.validation.js

@@ -84,6 +84,8 @@ function validatePersistence() {
     if (!parsed.success)
         return zodIssuesToLines('persistence', parsed.error);
     if (adapter === 'resource') {
+        if (!resourceName)
+            return ['persistence.resourceName: Missing opencore_db_resource'];
         const db = exports[resourceName];
         if (!db) {
             return [

package/dist/runtime/server/bus/core-event-bus.js

@@ -5,8 +5,11 @@ exports.emitFrameworkEvent = emitFrameworkEvent;
 const logger_1 = require("../../../kernel/shared/logger");
 const handlers = {};
 function onFrameworkEvent(event, handler) {
-    var _a;
-    const list = ((_a = handlers[event]) !== null && _a !== void 0 ? _a : (handlers[event] = []));
+    let list = handlers[event];
+    if (!list) {
+        list = [];
+        handlers[event] = list;
+    }
     list.push(handler);
     return () => {
         const index = list.indexOf(handler);

package/dist/runtime/server/controllers/principal-export.controller.js

@@ -16,8 +16,8 @@ exports.PrincipalExportController = void 0;
 const tsyringe_1 = require("tsyringe");
 const utils_1 = require("../../../kernel/utils");
 const index_1 = require("../contracts/index");
-const index_2 = require("../decorators/index");
 const export_1 = require("../decorators/export");
+const index_2 = require("../decorators/index");
 const player_directory_port_1 = require("../services/ports/player-directory.port");
 /**
  * Exports principal/permission functionality for RESOURCE mode access.

package/dist/runtime/server/decorators/throttle.js

@@ -43,6 +43,7 @@ const metadata_server_keys_1 = require("../system/metadata-server.keys");
  */
 function Throttle(optionsOrLimit, windowMs) {
     return (target, propertyKey, descriptor) => {
+        var _a;
         if (!descriptor) {
             // In benchmarks or edge cases, skip method wrapping
             // This should NOT happen in production code with proper TypeScript compilation
@@ -57,6 +58,7 @@ function Throttle(optionsOrLimit, windowMs) {
         else {
             opts = Object.assign({ onExceed: 'LOG' }, optionsOrLimit);
         }
+        const onExceed = (_a = opts.onExceed) !== null && _a !== void 0 ? _a : 'LOG';
         // Store metadata for remote transmission
         Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.THROTTLE, opts, target, propertyKey);
         descriptor.value = async function (...args) {
@@ -65,7 +67,7 @@ function Throttle(optionsOrLimit, windowMs) {
                 const service = tsyringe_1.container.resolve(rate_limiter_service_1.RateLimiterService);
                 const key = `${player.clientID}:${target.constructor.name}:${propertyKey}`;
                 if (!service.checkLimit(key, opts.limit, opts.windowMs)) {
-                    throw new security_error_1.SecurityError(opts.onExceed, opts.message || `Rate limit exceeded on ${propertyKey}`, { limit: opts.limit, key });
+                    throw new security_error_1.SecurityError(onExceed, opts.message || `Rate limit exceeded on ${propertyKey}`, { limit: opts.limit, key });
                 }
             }
             return originalMethod.apply(this, args);

package/dist/runtime/server/helpers/command-validation.helper.d.ts

@@ -3,4 +3,4 @@ import { Player } from '../entities';
 /**
  * Centraliza validación de argumentos de comandos.
  */
-export declare function validateAndExecuteCommand(meta: CommandMetadata, player: Player, args: string[], handler: Function): Promise<any>;
+export declare function validateAndExecuteCommand(meta: CommandMetadata, player: Player, args: string[], handler: (...args: any[]) => any): Promise<any>;

package/dist/runtime/server/helpers/function-helper.d.ts

@@ -1 +1 @@
-export declare function getParameterNames(func: Function): string[];
+export declare function getParameterNames(func: (...args: any[]) => any): string[];

package/dist/runtime/server/services/core/command.service.d.ts

@@ -22,7 +22,7 @@ export declare class CommandService extends CommandExecutionPort {
      * @param meta - Command metadata collected from the {@link Command} decorator.
      * @param handler - The bound method to invoke.
      */
-    register(meta: CommandMetadata, handler: Function): void;
+    register(meta: CommandMetadata, handler: (...args: any[]) => any): void;
     /**
      * Executes a registered command.
      *

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

@@ -305,12 +305,16 @@ class WorkerPool extends SimpleEventEmitter {
             const idleWorker = this.findIdleWorker();
             if (idleWorker) {
                 const task = this.taskQueue.shift();
+                if (!task)
+                    break;
                 this.assignTask(idleWorker, task);
             }
             else if (this.workers.size < this.config.maxWorkers) {
                 const newWorker = this.spawnWorker();
                 if (newWorker) {
                     const task = this.taskQueue.shift();
+                    if (!task)
+                        break;
                     this.assignTask(newWorker, task);
                 }
                 else {

package/dist/runtime/server/services/ports/command-execution.port.d.ts

@@ -25,7 +25,7 @@ export declare abstract class CommandExecutionPort {
      * @param metadata - Command metadata from decorator
      * @param handler - Bound method to invoke when command is executed
      */
-    abstract register(metadata: CommandMetadata, handler: Function): void;
+    abstract register(metadata: CommandMetadata, handler: (...args: any[]) => any): void;
     /**
      * Executes a registered command.
      *

package/dist/runtime/server/services/remote/remote-command.service.d.ts

@@ -36,7 +36,7 @@ export declare class RemoteCommandService extends CommandExecutionPort {
      * The handler and full metadata are stored locally for schema validation.
      * Only serializable metadata is sent to CORE for security validation.
      */
-    register(metadata: CommandMetadata, handler: Function): void;
+    register(metadata: CommandMetadata, handler: (...args: any[]) => any): void;
     /**
      * Executes a command handler stored in this resource.
      *

package/dist/runtime/server/services/services.register.js

@@ -9,13 +9,13 @@ const player_service_1 = require("./core/player.service");
 const principal_service_1 = require("./core/principal.service");
 const http_service_1 = require("./http/http.service");
 const persistence_service_1 = require("./persistence.service");
-const player_session_lifecycle_port_1 = require("./ports/player-session-lifecycle.port");
+const command_execution_port_1 = require("./ports/command-execution.port");
 const player_directory_port_1 = require("./ports/player-directory.port");
+const player_session_lifecycle_port_1 = require("./ports/player-session-lifecycle.port");
 const principal_port_1 = require("./ports/principal.port");
 const remote_command_service_1 = require("./remote/remote-command.service");
 const remote_player_service_1 = require("./remote/remote-player.service");
 const remote_principal_service_1 = require("./remote/remote-principal.service");
-const command_execution_port_1 = require("./ports/command-execution.port");
 /**
  * Registers server runtime services in the dependency injection container.
  *