@open-core/framework 0.1.0-alpha.1 → 0.2.0-beta.1

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

@@ -0,0 +1,54 @@
+import { BindingScope } from './bind';
+/**
+ * Marks a class as a framework-managed Service.
+ *
+ *
+ * @remarks
+ * This decorator binds the class into the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Service()` is a convenience wrapper over {@link Bind}. It exists so service-specific behavior
+ * can be added in the future without changing user code.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Service()
+ * export class InventoryService {
+ *   addItem() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Service(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;
+/**
+ * Marks a class as a Repository within the framework.
+ *
+ *
+ * @remarks
+ * A repository abstracts persistence operations (database, API, in-memory, or hybrid storage).
+ * It is registered in the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Repo()` is intentionally separate from {@link Service} to distinguish persistence-oriented
+ * classes from business logic.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Repo()
+ * export class AccountRepository {
+ *   async findById(id: string) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Repo(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;

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

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = Service;
+exports.Repo = Repo;
+const bind_1 = require("./bind");
+/**
+ * Marks a class as a framework-managed Service.
+ *
+ *
+ * @remarks
+ * This decorator binds the class into the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Service()` is a convenience wrapper over {@link Bind}. It exists so service-specific behavior
+ * can be added in the future without changing user code.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Service()
+ * export class InventoryService {
+ *   addItem() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function Service(options) {
+    var _a;
+    return (0, bind_1.Bind)((_a = options === null || options === void 0 ? void 0 : options.scope) !== null && _a !== void 0 ? _a : 'singleton');
+}
+/**
+ * Marks a class as a Repository within the framework.
+ *
+ *
+ * @remarks
+ * A repository abstracts persistence operations (database, API, in-memory, or hybrid storage).
+ * It is registered in the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Repo()` is intentionally separate from {@link Service} to distinguish persistence-oriented
+ * classes from business logic.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Repo()
+ * export class AccountRepository {
+ *   async findById(id: string) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function Repo(options) {
+    var _a;
+    return (0, bind_1.Bind)((_a = options === null || options === void 0 ? void 0 : options.scope) !== null && _a !== void 0 ? _a : 'singleton');
+}

package/dist/runtime/server/devmode/contracts/IDevModeBridge.d.ts

@@ -0,0 +1,36 @@
+import { BridgeMessage } from '../types';
+/**
+ * Contract for the WebSocket bridge between framework and CLI.
+ *
+ * Enables real-time communication for log streaming, event monitoring,
+ * and remote commands during development.
+ */
+export declare abstract class IDevModeBridge {
+    /**
+     * Connects to the CLI WebSocket server.
+     * @param url - WebSocket URL to connect to
+     */
+    abstract connect(url: string): Promise<void>;
+    /**
+     * Disconnects from the CLI.
+     */
+    abstract disconnect(): void;
+    /**
+     * Sends a message to the CLI.
+     * @param message - Message to send
+     */
+    abstract send(message: BridgeMessage): void;
+    /**
+     * Registers a message handler.
+     * @param handler - Function to handle incoming messages
+     */
+    abstract onMessage(handler: (message: BridgeMessage) => void): void;
+    /**
+     * Checks if currently connected.
+     */
+    abstract isConnected(): boolean;
+    /**
+     * Gets the current connection URL.
+     */
+    abstract getUrl(): string | null;
+}

package/dist/runtime/server/devmode/contracts/IDevModeBridge.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDevModeBridge = void 0;
+/**
+ * Contract for the WebSocket bridge between framework and CLI.
+ *
+ * Enables real-time communication for log streaming, event monitoring,
+ * and remote commands during development.
+ */
+class IDevModeBridge {
+}
+exports.IDevModeBridge = IDevModeBridge;

package/dist/runtime/server/devmode/contracts/IDevModeInspector.d.ts

@@ -0,0 +1,52 @@
+import { RuntimeSnapshot } from '../types';
+/**
+ * Handler metadata for inspection.
+ */
+export interface HandlerInfo {
+    name: string;
+    controller: string;
+    method: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * DI registration info for inspection.
+ */
+export interface DIRegistration {
+    token: string;
+    implementation: string;
+    lifecycle: 'singleton' | 'transient';
+}
+/**
+ * Contract for inspecting runtime state during development.
+ *
+ * Provides insights into registered handlers, DI container state,
+ * and player information for debugging purposes.
+ */
+export declare abstract class IDevModeInspector {
+    /**
+     * Captures a complete snapshot of the current runtime state.
+     * @returns Runtime snapshot with all relevant information
+     */
+    abstract captureSnapshot(): RuntimeSnapshot;
+    /**
+     * Gets all registered handlers grouped by type.
+     * @returns Map of handler type to handler info array
+     */
+    abstract getRegisteredHandlers(): Map<string, HandlerInfo[]>;
+    /**
+     * Gets the DI container registration graph.
+     * @returns Array of DI registrations
+     */
+    abstract getDIGraph(): DIRegistration[];
+    /**
+     * Gets player states for all connected players.
+     * @returns Map of client ID to state array
+     */
+    abstract getPlayerStates(): Map<number, string[]>;
+    /**
+     * Gets detailed info for a specific handler.
+     * @param type - Handler type (command, netEvent, export, etc.)
+     * @param name - Handler name
+     */
+    abstract getHandlerInfo(type: string, name: string): HandlerInfo | null;
+}

package/dist/runtime/server/devmode/contracts/IDevModeInspector.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDevModeInspector = void 0;
+/**
+ * Contract for inspecting runtime state during development.
+ *
+ * Provides insights into registered handlers, DI container state,
+ * and player information for debugging purposes.
+ */
+class IDevModeInspector {
+}
+exports.IDevModeInspector = IDevModeInspector;

package/dist/runtime/server/devmode/contracts/IDevModeInterceptor.d.ts

@@ -0,0 +1,41 @@
+import { DevEvent } from '../types';
+/**
+ * Contract for intercepting and recording runtime events.
+ *
+ * Used for debugging, monitoring, and replaying events during development.
+ */
+export declare abstract class IDevModeInterceptor {
+    /**
+     * Called before an event is processed.
+     * @param event - Event data without result/duration
+     */
+    abstract onEventBefore(event: Omit<DevEvent, 'result' | 'duration'>): void;
+    /**
+     * Called after an event completes successfully.
+     * @param event - Complete event data including result and duration
+     */
+    abstract onEventAfter(event: DevEvent): void;
+    /**
+     * Called when an event fails with an error.
+     * @param event - Event data with error information
+     */
+    abstract onEventError(event: DevEvent): void;
+    /**
+     * Gets the recorded event history.
+     * @returns Array of recorded events
+     */
+    abstract getEventHistory(): DevEvent[];
+    /**
+     * Clears the event history.
+     */
+    abstract clearHistory(): void;
+    /**
+     * Enables or disables event interception.
+     * @param enabled - Whether to enable interception
+     */
+    abstract setEnabled(enabled: boolean): void;
+    /**
+     * Checks if interception is enabled.
+     */
+    abstract isEnabled(): boolean;
+}

package/dist/runtime/server/devmode/contracts/IDevModeInterceptor.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDevModeInterceptor = void 0;
+/**
+ * Contract for intercepting and recording runtime events.
+ *
+ * Used for debugging, monitoring, and replaying events during development.
+ */
+class IDevModeInterceptor {
+}
+exports.IDevModeInterceptor = IDevModeInterceptor;

package/dist/runtime/server/devmode/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export { IDevModeBridge } from './IDevModeBridge';
+export { type DIRegistration, type HandlerInfo, IDevModeInspector } from './IDevModeInspector';
+export { IDevModeInterceptor } from './IDevModeInterceptor';

package/dist/runtime/server/devmode/contracts/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDevModeInterceptor = exports.IDevModeInspector = exports.IDevModeBridge = void 0;
+var IDevModeBridge_1 = require("./IDevModeBridge");
+Object.defineProperty(exports, "IDevModeBridge", { enumerable: true, get: function () { return IDevModeBridge_1.IDevModeBridge; } });
+var IDevModeInspector_1 = require("./IDevModeInspector");
+Object.defineProperty(exports, "IDevModeInspector", { enumerable: true, get: function () { return IDevModeInspector_1.IDevModeInspector; } });
+var IDevModeInterceptor_1 = require("./IDevModeInterceptor");
+Object.defineProperty(exports, "IDevModeInterceptor", { enumerable: true, get: function () { return IDevModeInterceptor_1.IDevModeInterceptor; } });

package/dist/runtime/server/devmode/dev-mode.service.d.ts

@@ -0,0 +1,110 @@
+import { EventInterceptorService } from './event-interceptor.service';
+import { PlayerSimulatorService } from './player-simulator.service';
+import { StateInspectorService } from './state-inspector.service';
+import { BridgeMessage, DevEvent, DevModeOptions, RuntimeSnapshot } from './types';
+/**
+ * Main DevMode service that orchestrates all development tools.
+ *
+ * Provides a unified interface for:
+ * - Hot reload server for automatic resource restarting
+ * - Event interception and recording
+ * - Runtime state inspection
+ * - Player simulation
+ * - Log streaming to external tools
+ */
+export declare class DevModeService {
+    private enabled;
+    private options;
+    private hotReloadServer;
+    private logTransport;
+    private get interceptor();
+    private get inspector();
+    private get simulator();
+    /**
+     * Enables DevMode with the specified options.
+     * @param options - DevMode configuration
+     */
+    enable(options: DevModeOptions): Promise<void>;
+    /**
+     * Disables DevMode and cleans up resources.
+     */
+    disable(): void;
+    /**
+     * Checks if DevMode is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Gets the current DevMode options.
+     */
+    getOptions(): DevModeOptions | null;
+    /**
+     * Connects to the CLI bridge for log streaming.
+     * Uses HTTP transport in FiveM, WebSocket in Node.js.
+     * @param url - Base URL (will be adapted based on environment)
+     */
+    connectToBridge(url: string): Promise<void>;
+    /**
+     * Disconnects from the CLI bridge.
+     */
+    disconnectFromBridge(): Promise<void>;
+    /**
+     * Sends a message to the CLI bridge (WebSocket only).
+     * In HTTP mode, messages are sent via log transport automatically.
+     * @param message - Message to send
+     */
+    sendToBridge(message: BridgeMessage): void;
+    /**
+     * Captures a snapshot of the current runtime state.
+     */
+    captureSnapshot(): RuntimeSnapshot;
+    /**
+     * Gets a summary of the current runtime state.
+     */
+    getSummary(): ReturnType<StateInspectorService['getSummary']>;
+    /**
+     * Gets detailed information about a specific player.
+     * @param clientId - Client ID
+     */
+    getPlayerDetails(clientId: number): Record<string, unknown> | null;
+    /**
+     * Gets the recorded event history.
+     */
+    getEventHistory(): DevEvent[];
+    /**
+     * Clears the event history.
+     */
+    clearEventHistory(): void;
+    /**
+     * Gets event statistics.
+     */
+    getEventStatistics(): ReturnType<EventInterceptorService['getStatistics']>;
+    /**
+     * Adds a listener for events.
+     * @param listener - Event listener function
+     * @returns Unsubscribe function
+     */
+    onEvent(listener: (event: DevEvent) => void): () => void;
+    /**
+     * Connects a simulated player.
+     * @param options - Player options
+     */
+    connectPlayer(options?: Parameters<PlayerSimulatorService['connect']>[0]): import("./types").SimulatedPlayer;
+    /**
+     * Disconnects a simulated player.
+     * @param clientId - Client ID
+     */
+    disconnectPlayer(clientId: number): void;
+    /**
+     * Connects multiple simulated players.
+     * @param count - Number of players
+     * @param options - Base options
+     */
+    connectPlayers(count: number, options?: Parameters<PlayerSimulatorService['connect']>[0]): import("./types").SimulatedPlayer[];
+    /**
+     * Gets simulated player statistics.
+     */
+    getSimulatorStatistics(): ReturnType<PlayerSimulatorService['getStatistics']>;
+    private handleBridgeMessage;
+    private handleRemoteCommand;
+    private handleRemoteReload;
+}