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

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/internal-event.bus.d.ts

@@ -0,0 +1,6 @@
+import { InternalEventMap } from '../types/internal-events';
+type InternalEventName = keyof InternalEventMap;
+type InternalEventHandler<E extends InternalEventName> = (payload: InternalEventMap[E]) => void;
+export declare function onFrameworkEvent<E extends InternalEventName>(event: E, handler: InternalEventHandler<E>): () => void;
+export declare function emitFrameworkEvent<E extends InternalEventName>(event: E, payload: InternalEventMap[E]): void;
+export {};

package/dist/runtime/server/bus/{core-event-bus.js → internal-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/controllers/session.controller.js

@@ -11,7 +11,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionController = void 0;
 const shared_1 = require("../../../kernel/shared");
-const core_event_bus_1 = require("../bus/core-event-bus");
+const internal_event_bus_1 = require("../bus/internal-event.bus");
 const decorators_1 = require("../decorators");
 const onFiveMEvent_1 = require("../decorators/onFiveMEvent");
 const services_1 = require("../services");
@@ -33,12 +33,12 @@ let SessionController = class SessionController {
             license: license !== null && license !== void 0 ? license : 'none',
         });
         await this.persistance.handleSessionLoad(player);
-        (0, core_event_bus_1.emitFrameworkEvent)('core:playerSessionCreated', { clientId, license });
+        (0, internal_event_bus_1.emitFrameworkEvent)('internal:playerSessionCreated', { clientId, license });
         setImmediate(() => {
             const currentPlayer = this.playerDirectory.getByClient(clientId);
             if (!currentPlayer)
                 return;
-            (0, core_event_bus_1.emitFrameworkEvent)('core:playerFullyConnected', { clientId, license });
+            (0, internal_event_bus_1.emitFrameworkEvent)('internal:playerFullyConnected', currentPlayer);
         });
     }
     async onPlayerDropped() {
@@ -48,7 +48,7 @@ let SessionController = class SessionController {
             await this.persistance.handleSessionSave(player);
         }
         this.playerSessionLifecycle.unbind(clientId);
-        (0, core_event_bus_1.emitFrameworkEvent)('core:playerSessionDestroyed', { clientId });
+        (0, internal_event_bus_1.emitFrameworkEvent)('internal:playerSessionDestroyed', { clientId });
         shared_1.loggers.session.info(`Player session destroyed`, { clientId });
     }
 };

package/dist/runtime/server/decorators/onFrameworkEvent.d.ts

@@ -1,4 +1,9 @@
-import { CoreEventMap } from '../types/core-events';
+import { InternalEventMap } from '../types/internal-events';
+/**
+ * Handler function type for framework events.
+ * Accepts the event payload and returns void or Promise<void>.
+ */
+type FrameworkEventHandler<K extends keyof InternalEventMap> = (payload: InternalEventMap[K]) => void | Promise<void>;
 /**
  * Registers a method as a listener for an internal OpenCore framework event.
  *
@@ -6,17 +11,21 @@ import { CoreEventMap } from '../types/core-events';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * @param event - Core event name, strongly typed to {@link CoreEventMap}.
+ * The method signature is type-checked against the event payload. TypeScript will error if
+ * the handler parameter type doesn't match the expected payload for the specified event.
+ *
+ * @param event - Core event name, strongly typed to {@link InternalEventMap}.
  *
  * @example
  * ```ts
  * @Server.Controller()
  * export class SystemController {
- *   @Server.OnFrameworkEvent('server:ready')
- *   onServerReady() {
- *     console.log('OpenCore framework is ready')
+ *   @Server.OnFrameworkEvent('core:playerSessionCreated')
+ *   onPlayerSession(payload: PlayerSessionCreatedPayload) {
+ *     console.log(`Player ${payload.clientId} connected`)
  *   }
  * }
  * ```
  */
-export declare function OnFrameworkEvent<K extends keyof CoreEventMap>(event: K): (target: any, propertyKey: string) => void;
+export declare function OnFrameworkEvent<K extends keyof InternalEventMap>(event: K): (target: object, propertyKey: string | symbol, _descriptor: TypedPropertyDescriptor<FrameworkEventHandler<K>>) => void;
+export {};

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

@@ -9,21 +9,24 @@ const metadata_server_keys_1 = require("../system/metadata-server.keys");
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * @param event - Core event name, strongly typed to {@link CoreEventMap}.
+ * The method signature is type-checked against the event payload. TypeScript will error if
+ * the handler parameter type doesn't match the expected payload for the specified event.
+ *
+ * @param event - Core event name, strongly typed to {@link InternalEventMap}.
  *
  * @example
  * ```ts
  * @Server.Controller()
  * export class SystemController {
- *   @Server.OnFrameworkEvent('server:ready')
- *   onServerReady() {
- *     console.log('OpenCore framework is ready')
+ *   @Server.OnFrameworkEvent('core:playerSessionCreated')
+ *   onPlayerSession(payload: PlayerSessionCreatedPayload) {
+ *     console.log(`Player ${payload.clientId} connected`)
  *   }
  * }
  * ```
  */
 function OnFrameworkEvent(event) {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.CORE_EVENT, { event }, target, propertyKey);
+    return (target, propertyKey, _descriptor) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.INTERNAL_EVENT, { event }, target, propertyKey);
     };
 }