@open-core/framework 1.0.7 → 1.0.9

package/README.md

@@ -141,6 +141,44 @@ export class ExampleNetController {
 - `@Throttle(limit, windowMs)`
 - `@RequiresState({ missing: [...] })`
 
+### Exports
+
+`@Export()` defines a public resource API. Adapters may expose both direct/local access through `getResource()` and an optional explicit async helper layer through `getRemoteResource()` / `waitForRemoteResource()`.
+
+```ts
+import { Controller, Export } from '@open-core/framework/server'
+import { IExports } from '@open-core/framework/contracts/server'
+
+@Controller()
+export class DatabaseController {
+  @Export('pingDatabase')
+  async pingDatabase() {
+    return { success: true }
+  }
+}
+
+interface DatabaseExports {
+  pingDatabase(): Promise<{ success: boolean }>
+}
+
+class ExampleConsumer {
+  constructor(private readonly exportsService: IExports) {}
+
+  async ping() {
+    const database = await this.exportsService.waitForRemoteResource<DatabaseExports>('database', {
+      exportName: 'pingDatabase',
+    })
+
+    return database.pingDatabase()
+  }
+}
+```
+
+Guidance:
+
+- `getResource()` is for local/synchronous resolution used by framework internals.
+- `waitForRemoteResource()` / `getRemoteResource()` are optional adapter utilities for explicit async resource-to-resource calls.
+
 ### Library events
 
 Use library wrappers to emit domain events and `@OnLibraryEvent()` to observe them.

package/dist/adapters/contracts/IExports.d.ts

@@ -1,4 +1,42 @@
 export declare abstract class IExports {
+    /**
+     * Registers a local export handler for the current resource.
+     *
+     * @remarks
+     * This is called by the framework during metadata processing when it discovers
+     * methods decorated with `@Export()`.
+     */
     abstract register(exportName: string, handler: (...args: unknown[]) => unknown): void;
+    /**
+     * Resolves exports for a resource using the adapter's direct/local mechanism.
+     *
+     * @remarks
+     * Framework internals rely on this method remaining synchronous and side-effect free.
+     * Adapters should return `undefined` when the resource is not directly resolvable.
+     */
     abstract getResource<T = unknown>(resourceName: string): T | undefined;
+    /**
+     * Returns an async proxy for resource exports when the adapter provides a remote helper layer.
+     *
+     * @remarks
+     * This is optional and should not change the semantics of `getResource()`.
+     * Consumers should treat methods on the returned proxy as async.
+     */
+    getRemoteResource<T = unknown>(_resourceName: string): T;
+    /**
+     * Calls a single exported method through the adapter's optional remote helper layer.
+     */
+    callRemoteExport<TResult = unknown>(_resourceName: string, _exportName: string, ..._args: unknown[]): Promise<TResult>;
+    /**
+     * Waits until a resource exposes exports compatible with the adapter's remote helper layer.
+     *
+     * @param _options.exportName Optional export name that must be present before resolving.
+     * @param _options.timeoutMs Maximum time to wait before failing.
+     * @param _options.intervalMs Polling interval used by adapters that implement polling.
+     */
+    waitForRemoteResource<T = unknown>(_resourceName: string, _options?: {
+        exportName?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<T>;
 }

package/dist/adapters/contracts/IExports.js

@@ -1,2 +1,28 @@
 export class IExports {
+    /**
+     * Returns an async proxy for resource exports when the adapter provides a remote helper layer.
+     *
+     * @remarks
+     * This is optional and should not change the semantics of `getResource()`.
+     * Consumers should treat methods on the returned proxy as async.
+     */
+    getRemoteResource(_resourceName) {
+        throw new Error('[OpenCore] Remote exports are not supported by the active adapter.');
+    }
+    /**
+     * Calls a single exported method through the adapter's optional remote helper layer.
+     */
+    callRemoteExport(_resourceName, _exportName, ..._args) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported by the active adapter.'));
+    }
+    /**
+     * Waits until a resource exposes exports compatible with the adapter's remote helper layer.
+     *
+     * @param _options.exportName Optional export name that must be present before resolving.
+     * @param _options.timeoutMs Maximum time to wait before failing.
+     * @param _options.intervalMs Polling interval used by adapters that implement polling.
+     */
+    waitForRemoteResource(_resourceName, _options) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported by the active adapter.'));
+    }
 }

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

@@ -7,6 +7,13 @@ export declare class NodeExports implements IExports {
     private exports;
     register(exportName: string, handler: (...args: any[]) => any): void;
     getResource(resourceName: string): any;
+    getRemoteResource<T = unknown>(_resourceName: string): T;
+    callRemoteExport<TResult = unknown>(_resourceName: string, _exportName: string, ..._args: unknown[]): Promise<TResult>;
+    waitForRemoteResource<T = unknown>(_resourceName: string, _options?: {
+        exportName?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<T>;
     /**
      * Get all registered exports as an object
      */

package/dist/adapters/node/node-exports.js

@@ -23,6 +23,15 @@ let NodeExports = class NodeExports {
         throw new Error(`Cross-resource exports not supported in Node.js runtime. ` +
             `Attempted to access resource: ${resourceName}`);
     }
+    getRemoteResource(_resourceName) {
+        throw new Error('[OpenCore] Remote exports are not supported in Node.js runtime.');
+    }
+    callRemoteExport(_resourceName, _exportName, ..._args) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported in Node.js runtime.'));
+    }
+    waitForRemoteResource(_resourceName, _options) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported in Node.js runtime.'));
+    }
     /**
      * Get all registered exports as an object
      */

package/dist/runtime/server/bootstrap.js

@@ -5,9 +5,11 @@ import { GLOBAL_CONTAINER, MetadataScanner } from '../../kernel/di/index';
 import { getLogLevel, LogLevelLabels, loggers } from '../../kernel/logger';
 import { createNodeServerAdapter } from './adapter/node-server-adapter';
 import { installServerAdapter } from './adapter/registry';
+import { configureFrameworkEventBridge } from './bus/internal-event.bus';
 import { PrincipalProviderContract } from './contracts/index';
 import { getServerBinaryServiceRegistry } from './decorators/binaryService';
 import { getServerControllerRegistry } from './decorators/controller';
+import { Players } from './ports/players.api-port';
 import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } from './runtime';
 import { BinaryProcessManager } from './system/managers/binary-process.manager';
 import { PlayerPersistenceService } from './services/persistence.service';
@@ -116,6 +118,13 @@ export async function initServer(options, plugins) {
     // 1. Register Core Services (WorldContext, PlayerService, etc.)
     registerServicesServer(ctx);
     loggers.bootstrap.debug('Core services registered');
+    configureFrameworkEventBridge({
+        mode: ctx.mode,
+        engineEvents: GLOBAL_CONTAINER.resolve(IEngineEvents),
+        players: GLOBAL_CONTAINER.isRegistered(Players)
+            ? GLOBAL_CONTAINER.resolve(Players)
+            : undefined,
+    });
     // 2. Load Controllers (Framework & User controllers)
     // This is where user services get registered if they are decorated with @injectable()
     // and imported before init() or discovered here.
@@ -269,13 +278,32 @@ async function tryImportAutoLoad() {
         await import('./.opencore/autoload.server.controllers');
     }
     catch (err) {
-        if (err instanceof Error && err.message.includes('Cannot find module')) {
+        if (isAutoloadModuleNotFound(err)) {
             loggers.bootstrap.warn(`[Bootstrap] No server controllers autoload file found, skipping.`);
             return;
         }
+        const message = err instanceof Error ? err.message : String(err);
+        loggers.bootstrap.error(`[Bootstrap] Failed to import server controllers autoload file.`, {
+            error: message,
+        });
         throw err;
     }
 }
+function isAutoloadModuleNotFound(err) {
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    const error = err;
+    const message = typeof error.message === 'string' ? error.message : '';
+    const requireStack = Array.isArray(error.requireStack) ? error.requireStack : [];
+    if (error.code !== 'MODULE_NOT_FOUND' && !message.includes('Cannot find module')) {
+        return false;
+    }
+    if (message.includes('autoload.server.controllers')) {
+        return true;
+    }
+    return requireStack.some((entry) => entry.includes('autoload.server.controllers'));
+}
 /**
  * Runs session recovery to restore sessions for players already connected.
  *

package/dist/runtime/server/bus/internal-event.bus.d.ts

@@ -1,6 +1,15 @@
-import { FrameworkEventsMap } from '../types/framework-events.types';
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { type FrameworkMode } from '../runtime';
+import { Players } from '../ports/players.api-port';
+import { type FrameworkEventsMap } from '../types/framework-events.types';
 type InternalEventName = keyof FrameworkEventsMap;
 type InternalEventHandler<E extends InternalEventName> = (payload: FrameworkEventsMap[E]) => void;
+interface FrameworkEventBridgeConfig {
+    mode: FrameworkMode;
+    engineEvents?: IEngineEvents;
+    players?: Players;
+}
 export declare function onFrameworkEvent<E extends InternalEventName>(event: E, handler: InternalEventHandler<E>): () => void;
+export declare function configureFrameworkEventBridge(config: FrameworkEventBridgeConfig): void;
 export declare function emitFrameworkEvent<E extends InternalEventName>(event: E, payload: FrameworkEventsMap[E]): void;
 export {};

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

@@ -1,5 +1,10 @@
 import { loggers } from '../../../kernel/logger';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 const handlers = {};
+const bridgeListenerRegistrations = new WeakSet();
+let bridgeConfig = {
+    mode: 'STANDALONE',
+};
 export function onFrameworkEvent(event, handler) {
     let list = handlers[event];
     if (!list) {
@@ -13,7 +18,32 @@ export function onFrameworkEvent(event, handler) {
             list.splice(index, 1);
     };
 }
+export function configureFrameworkEventBridge(config) {
+    bridgeConfig = config;
+    if (config.mode !== 'RESOURCE' || !config.engineEvents)
+        return;
+    if (bridgeListenerRegistrations.has(config.engineEvents))
+        return;
+    config.engineEvents.on(SYSTEM_EVENTS.framework.dispatch, (envelope) => {
+        if (bridgeConfig.mode !== 'RESOURCE')
+            return;
+        dispatchTransportFrameworkEvent(envelope.event, envelope.payload);
+    });
+    bridgeListenerRegistrations.add(config.engineEvents);
+}
 export function emitFrameworkEvent(event, payload) {
+    dispatchLocalFrameworkEvent(event, payload);
+    if (bridgeConfig.mode !== 'CORE' || !bridgeConfig.engineEvents)
+        return;
+    const transportPayload = serializeFrameworkEvent(event, payload);
+    if (!transportPayload)
+        return;
+    bridgeConfig.engineEvents.emit(SYSTEM_EVENTS.framework.dispatch, {
+        event,
+        payload: transportPayload,
+    });
+}
+function dispatchLocalFrameworkEvent(event, payload) {
     const list = handlers[event];
     if (!list)
         return;
@@ -28,3 +58,68 @@ export function emitFrameworkEvent(event, payload) {
         }
     }
 }
+function dispatchTransportFrameworkEvent(event, payload) {
+    const hydrated = hydrateFrameworkEvent(event, payload);
+    if (!hydrated)
+        return;
+    dispatchLocalFrameworkEvent(event, hydrated);
+}
+function serializeFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            return {
+                clientId: fullyConnectedPayload.player.clientID,
+            };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+            };
+        }
+        default:
+            return null;
+    }
+}
+function hydrateFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            const player = bridgeConfig.players?.getByClient(fullyConnectedPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: fullyConnectedPayload.clientId,
+                });
+                return null;
+            }
+            return { player };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            const player = bridgeConfig.players?.getByClient(recoveredPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: recoveredPayload.clientId,
+                });
+                return null;
+            }
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+                player,
+            };
+        }
+        default:
+            return null;
+    }
+}

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

@@ -6,7 +6,23 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

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

@@ -6,7 +6,23 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

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

@@ -7,6 +7,19 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

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

@@ -7,6 +7,19 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

package/dist/runtime/server/types/framework-events.types.d.ts

@@ -1,19 +1,65 @@
 import { Player } from '../entities';
+/**
+ * Emitted when a player session is created in the framework session lifecycle.
+ */
 export interface PlayerSessionCreatedPayload {
     clientId: number;
     license: string | undefined;
 }
+/**
+ * Emitted when a player session is destroyed in the framework session lifecycle.
+ */
 export interface PlayerSessionDestroyedPayload {
     clientId: number;
 }
+/**
+ * Emitted when the framework considers the player fully connected and the runtime-specific
+ * {@link Player} entity can be consumed safely by application code.
+ */
 export interface PlayerFullyConnectedPayload {
     player: Player;
 }
+/**
+ * Emitted when the framework recreates a player session after resource restart recovery.
+ */
 export interface PlayerSessionRecoveredPayload {
     clientId: number;
     player: Player;
     license: string | undefined;
 }
+/**
+ * Serialized transport payload for `internal:playerFullyConnected` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerFullyConnectedTransportPayload {
+    clientId: number;
+}
+/**
+ * Serialized transport payload for `internal:playerSessionRecovered` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerSessionRecoveredTransportPayload {
+    clientId: number;
+    license: string | undefined;
+}
+/**
+ * Internal transport contract used by the framework bridge when delivering framework events
+ * between different server runtimes.
+ */
+export type FrameworkTransportEventsMap = {
+    'internal:playerSessionCreated': PlayerSessionCreatedPayload;
+    'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;
+    'internal:playerFullyConnected': PlayerFullyConnectedTransportPayload;
+    'internal:playerSessionRecovered': PlayerSessionRecoveredTransportPayload;
+};
+/**
+ * Envelope emitted through the internal framework bridge.
+ */
+export interface FrameworkEventEnvelope<E extends keyof FrameworkTransportEventsMap> {
+    event: E;
+    payload: FrameworkTransportEventsMap[E];
+}
+/**
+ * Public payload map consumed by {@link OnFrameworkEvent} and `onFrameworkEvent(...)`.
+ */
 export type FrameworkEventsMap = {
     'internal:playerSessionCreated': PlayerSessionCreatedPayload;
     'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;

package/dist/runtime/shared/types/system-types.d.ts

@@ -16,6 +16,9 @@ export declare const SYSTEM_EVENTS: {
     readonly command: {
         readonly execute: `opencore:${string}:${string}`;
     };
+    readonly framework: {
+        readonly dispatch: `opencore:${string}:${string}`;
+    };
     readonly spawner: {
         readonly spawn: `opencore:${string}:${string}`;
         readonly teleport: `opencore:${string}:${string}`;

package/dist/runtime/shared/types/system-types.js

@@ -17,6 +17,9 @@ export const SYSTEM_EVENTS = {
     command: {
         execute: systemEvent('command', 'execute'),
     },
+    framework: {
+        dispatch: systemEvent('framework', 'dispatch'),
+    },
     spawner: {
         spawn: systemEvent('spawner', 'spawn'),
         teleport: systemEvent('spawner', 'teleport'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",