@aurora-mp/core/dist/index.d.ts

Core package of the aurora-mp TypeScript framework, providing dependency injection, event handling, and module registration.

/**
 * Represents a JavaScript class constructor that can be called with `new` to create instances of type T.
 *
 * @template T The type of object created by this constructor. Defaults to `unknown`.
 * @example
 * ```ts
 * class MyService {
 *   constructor(private name: string) {}
 * }
 * const serviceCtor: Type<MyService> = MyService;
 * const instance = new serviceCtor('Aurora');
 * ```
 * @public
 */
interface Type<T = unknown> {
    /**
     * Constructor signature for creating an instance of T.
     *
     * @param args Arguments passed to the class constructor.
     * @returns A new instance of type T.
     */
    new (...args: any[]): T;
}
/**
 * A token used to uniquely identify a provider in the DI container.
 * Tokens can be:
 * - A class constructor (`Type<T>`)
 * - A `string`
 * - A `symbol`
 *
 * @template T The type of the value represented by this token. Defaults to `any`.
 * @see {@link Type}
 * @public
 */
type Token<T = any> = Type<T> | string | symbol;

/**
 * Defines the available event types for controller decorators,
 * indicating which runtime source should trigger the handler.
 *
 * - `ON`: General in-game events from either client or server context.
 * - `ON_CLIENT`: Client-side events only.
 * - `ON_SERVER`: Server-side events only.
 *
 * @public
 */
declare enum EventType {
    /**
     * Listens to any event emitted by the platform driver,
     * regardless of client or server origin.
     */
    ON = "on",
    /**
     * Listens only to client-side events.
     */
    ON_CLIENT = "onClient",
    /**
     * Listens only to server-side events.
     */
    ON_SERVER = "onServer"
}

/**
 * Types of parameters that can be injected into controller event handlers.
 * Used by the parameter decorators to determine what data to supply.
 *
 * @public
 */
declare enum MethodParamType {
    /**
     * Injects the entire event payload object as the parameter value.
     */
    PAYLOAD = "payload",
    /**
     * Injects a specific property from the event payload.
     * The decorator’s `data` argument specifies the key to extract.
     */
    PARAM = "param",
    /**
     * Injects the player instance associated with the event,
     * if the event context provides one.
     */
    PLAYER = "player"
}

declare enum RpcType {
    ON_CLIENT = "onClientRpc",
    ON_SERVER = "onServerRpc"
}

/**
 * Defines the lifetime scopes for injectable providers in the Aurora DI container.
 *
 * @public
 */
declare enum Scope {
    /**
     * A single shared instance is created once and reused for all injections.
     */
    SINGLETON = 0,
    /**
     * A new instance is created every time the provider is injected.
     */
    TRANSIENT = 1
}

declare enum WebViewEvents {
    DISPATCH = "aurora:webview:dispatch",
    EMIT_SERVER = "aurora:webview:emitServer",
    INVOKE_SERVER_RPC = "aurora:webview:invokeServerRpc"
}

/**
 * Describes a controller method bound to a runtime event, including its type,
 * handler name, parameters to inject, and an optional WebView identifier.
 *
 * @public
 */
interface EventMetadata {
    /**
     * The type of event this handler listens for (e.g., ON, ON_CLIENT, ON_SERVER).
     */
    type: EventType;
    /**
     * The name of the event, used to match against emitted event names.
     */
    name: string;
    /**
     * The name of the controller method that will be invoked when the event fires.
     */
    methodName: string;
    /**
     * Metadata for each parameter of the handler method, indicating how to resolve
     * its value at runtime (payload, specific property, player, etc.).
     */
    params: MethodParameter[];
    /**
     * Optional identifier for targeting a specific WebView instance when the event
     * originates from a WebView context.
     */
    webViewId?: string | number;
    /**
     * List of Guard classes to run before calling the handler. Each guard
     * must implement the Guard interface and its `canActivate` method.
     */
    guards?: Type<Guard>[];
}

/**
 * Describes a provider that binds a token to a pre-existing value.
 * Useful for injecting configuration objects, constants, or mock objects in tests.
 *
 * @template T The type of the value to be injected.
 */
interface ValueProvider<T = any> {
    /**
     * The injection token used to identify this provider.
     */
    provide: Token<T>;
    /**
     * The actual value to be injected when the token is requested.
     */
    useValue: T;
    scope?: Scope;
}
/**
 * Describes a provider that binds a token to an instance of a specified class.
 * The DI container will instantiate the `useClass` and inject its dependencies.
 *
 * @template T The type of the class to be instantiated.
 */
interface ClassProvider<T = any> {
    /**
     * The injection token used to identify this provider.
     */
    provide: Token<T>;
    /**
     * The class to be instantiated and injected.
     */
    useClass: Type<T>;
    scope?: Scope;
}
/**
 * A provider that constructs via a factory function.
 */
interface FactoryProvider<T = unknown> {
    provide: Token<T>;
    useFactory: (...args: any[]) => T | Promise<T>;
    inject?: Array<{
        token: Token<any>;
        optional?: boolean;
    }>;
    scope?: Scope;
}
/**
 * Describes how a dependency should be provided. A provider can be:
 * - A class `Type` (shorthand for `{ provide: Type, useClass: Type }`).
 * - A `ValueProvider` object.
 * - A `ClassProvider` object.
 *
 * @template T The type of the provided value.
 */
type Provider<T = unknown> = Type<T> | ValueProvider<T> | ClassProvider<T> | FactoryProvider<T>;

/**
 * Defines the structure of a module’s configuration in the Aurora framework.
 * A module bundles related controllers, providers, and imports/exports into a cohesive unit.
 *
 * @public
 */
interface ModuleMetadata {
    /**
     * Other modules whose exported providers/controllers should be available
     * for injection within this module.
     *
     * @remarks
     * Imported modules’ exports are merged into this module’s DI scope.
     */
    imports?: Type[];
    /**
     * Controller classes that belong to this module.
     * These will be instantiated and have their event handlers bound at startup.
     */
    controllers?: Type[];
    /**
     * Provider definitions (classes or useValue objects) registered in this module’s DI container.
     * These are the services and values available for injection into controllers and other providers.
     */
    providers?: Provider[];
    /**
     * Tokens of providers or controllers that this module makes available
     * to modules that import it.
     *
     * @remarks
     * Only exported tokens can be consumed by importing modules.
     */
    exports?: Token[];
}

/**
 * Metadata describing a controller method exposed as an RPC handler.
 *
 * @public
 */
interface RpcMetadata {
    /**
     * The kind of RPC this handler processes (e.g., REQUEST, RESPONSE).
     */
    type: RpcType;
    /**
     * The RPC channel or name used to invoke this handler.
     */
    name: string;
    /**
     * The name of the class method that will be called for this RPC.
     */
    methodName: string;
    /**
     * Metadata for each parameter of the handler method, indicating how to
     * resolve its value at runtime (player object, payload, specific properties, etc.).
     */
    params: MethodParameter[];
    /**
     * When the RPC originates from a specific WebView, this can target that view.
     */
    webViewId?: string | number;
    /**
     * An optional list of Guard classes to run before executing the handler.
     * Each guard must implement the Guard interface's `canActivate` method.
     */
    guards?: Type<Guard>[];
}

interface AuroraPlugin {
    onInit?(app: IApplication): Promise<void> | void;
    onBootstrap?(app: IApplication): Promise<void> | void;
}

/**
 * Represents a bootstrapped Aurora application instance,
 * exposing methods to start, retrieve dependencies, and gracefully shut down.
 *
 * @public
 */
interface IApplication {
    /**
     * Attaches all controller event handlers to the platform driver
     * and starts listening for incoming events.
     * Call this after initializing the application to begin processing events.
     *
     * @returns A promise that resolves once the application has started.
     */
    start(): Promise<void>;
    /**
     * Retrieves an existing provider or controller instance from the root module’s DI context.
     *
     * @typeParam T The expected type of the resolved instance.
     * @param token The injection token or class constructor of the provider to resolve.
     * @returns A promise that resolves to the instance associated with the given token.
     * @throws If no provider is registered for the given token.
     */
    get<T = Token>(token: Token<T>): Promise<T>;
    /**
     * Performs a graceful shutdown of the application by invoking all
     * OnApplicationShutdown lifecycle hooks on controllers.
     *
     * @returns A promise that resolves once shutdown is complete.
     */
    close(): Promise<void>;
    usePlugins(...plugins: AuroraPlugin[]): this;
}

/**
 * Describes metadata for a single parameter of a controller event handler,
 * indicating what value should be injected at runtime.
 *
 * @public
 */
interface ArgumentMetadata {
    /**
     * The kind of parameter to inject (entire payload, single property, player object, etc.).
     */
    type: MethodParamType;
    /**
     * The zero-based position of this parameter in the method signature.
     */
    index: number;
    /**
     * Optional extra data for the decorator, such as the payload property key
     * when `type` is `MethodParamType.PARAM`.
     */
    data?: string;
}

/**
 * The contract for a service that can load configuration data.
 */
interface IConfigLoader {
    /**
     * Loads and parses the configuration source (e.g., a .env file).
     * @returns A record containing the configuration key-value pairs.
     */
    load(): Record<string, string>;
}

/**
 * The common interface for the configuration service.
 */
interface IConfigService {
    /**
     * Gets a configuration value.
     * @template T The expected type of the value.
     * @param key The key of the configuration property.
     * @param defaultValue An optional default value if the key is not found.
     * @returns The configuration value, or the default value.
     */
    get<T = any>(key: string, defaultValue?: T): T;
}

/**
 * Provides contextual information for a controller event invocation.
 * An instance of this interface is available to guards, interceptors,
 * and can be injected into handler methods as needed.
 *
 * @public
 */
interface ExecutionContext {
    /**
     * The name or identifier of the event being handled.
     */
    readonly name: string;
    /**
     * The raw arguments array received from the platform driver for this event.
     */
    readonly args: unknown[];
    /**
     * A convenient reference to the main payload of the event
     * (typically the first element of `args`).
     */
    readonly payload?: unknown;
    /**
     * The player object associated with the event, if one is present
     * in the platform event context.
     */
    readonly player?: unknown;
    /**
     * Returns the class (i.e. controller or provider) that defines the current handler.
     */
    getClass(): Type;
    /**
     * Returns the actual method (function) being executed.
     */
    getHandler(): Function;
    /**
     * Returns the player object, or undefined.
     */
    getPlayer(): unknown;
}

interface Guard {
    canActivate(context: ExecutionContext): boolean | Promise<boolean>;
}

/**
 * Configuration options for the {@link Injectable} decorator.
 * Allows customization of the provider’s lifetime scope.
 *
 * @public
 */
interface InjectableOptions {
    /**
     * The lifetime scope of the injectable provider.
     * - `Scope.SINGLETON` (default): a single shared instance.
     * - `Scope.TRANSIENT`: a new instance per injection.
     */
    scope?: Scope;
}

/**
 * Interface for a class that wishes to run logic after the application has been initialized.
 */
interface OnAppInit {
    onAppInit(): void;
}
/**
 * Interface for a class that wishes to run logic after the application has start.
 */
interface OnAppStarted {
    onAppStarted(): void;
}
/**
 * Interface for a class that wishes to run logic when the application is shutting down.
 * Useful for cleanup tasks like closing database connections.
 */
interface OnAppShutdown {
    /**
     * Method called when the application receives a shutdown signal.
     * @param signal The signal that triggered the shutdown (e.g., 'SIGINT').
     */
    onAppShutdown(signal?: string): void;
}

interface ILogger {
    debug(message: string): void;
    info(message: string): void;
    warn(message: string): void;
    error(message: string | Error): void;
}

interface BaseParameter extends ArgumentMetadata {
    metatype?: Function;
    method?: string;
    isOptional?: boolean;
    defaultValue?: any;
}
/**
 * Metadata for a controller method parameter that receives
 * the entire event payload.
 *
 * @public
 */
interface PayloadParameter extends BaseParameter {
    /**
     * The parameter kind: inject the full payload object.
     */
    type: MethodParamType.PAYLOAD;
}
/**
 * Metadata for a controller method parameter that receives
 * a specific property from the event payload.
 *
 * @public
 */
interface ParamParameter extends BaseParameter {
    /**
     * The parameter kind: inject a single payload property.
     */
    type: MethodParamType.PARAM;
    /**
     * The key of the property to extract from the payload.
     */
    data: string;
}
/**
 * Metadata for a controller method parameter that receives
 * the player instance associated with the event.
 *
 * @public
 */
interface PlayerParameter extends BaseParameter {
    /**
     * The parameter kind: inject the player object.
     */
    type: MethodParamType.PLAYER;
}
/**
 * Union type covering all possible controller method
 * parameter metadata shapes (payload, single property, or player).
 *
 * @public
 */
type MethodParameter = PayloadParameter | ParamParameter | PlayerParameter;

/**
 * Minimal cross-platform abstraction for a browser-based UI instance.
 * Mirrors common APIs for alt:V, RageMP, etc.
 */
interface IWebView {
    emit(event: string, ...args: unknown[]): void;
    destroy(): void;
}

/**
 * Defines an abstraction over the underlying multiplayer platform’s
 * event, RPC, and WebView mechanisms. Implement this interface to
 * integrate Aurora with a specific platform driver.
 *
 * @template TPlayer - The native player type provided by the platform
 *   (e.g., server or client player object).
 * @public
 */
interface IPlatformDriver<TPlayer = unknown> {
    /**
     * Registers a listener for a general platform event.
     *
     * @param eventName - The event identifier (e.g., 'playerConnect', 'resourceStart').
     * @param listener - Called with the raw event arguments when the event fires.
     */
    on(eventName: string, listener: (...args: unknown[]) => void): void;
    /**
     * Unregisters a listener for a general platform event.
     *
     * @param eventName - The event identifier.
     * @param listener - The callback to remove.
     */
    off?(eventName: string, listener: (...args: unknown[]) => void): void;
    /**
     * Registers a listener for a client-originated event.
     *
     * @param eventName - The client event identifier.
     * @param listener - Called with the player instance and event arguments.
     */
    onClient?(eventName: string, listener: (player: TPlayer, ...args: unknown[]) => void): void;
    /**
     * Registers a listener for a server-originated event.
     *
     * @param eventName - The server event identifier.
     * @param listener - Called with the player instance and event arguments.
     */
    onServer?(eventName: string, listener: (player: TPlayer, ...args: unknown[]) => void): void;
    /**
     * Emits a general event to all listeners (server or client).
     *
     * @param eventName - The event identifier to emit.
     * @param args - Arguments to pass to the event handlers.
     */
    emit(eventName: string, ...args: unknown[]): void;
    /**
     * Emits a server-specific event to all server-side listeners.
     *
     * @param eventName - The server event identifier to emit.
     * @param args - Arguments to pass to the server handlers.
     */
    emitServer?(eventName: string, ...args: unknown[]): void;
    /**
     * Emits a client-specific event to a single player.
     *
     * @param player - The target player instance.
     * @param eventName - The client event identifier to emit.
     * @param args - Arguments to pass to the client handler.
     */
    emitClient?(player: TPlayer, eventName: string, ...args: unknown[]): void;
    /**
     * Invokes a server-side RPC and returns its result.
     *
     * @typeParam T - The expected return type of the RPC.
     * @param rpcName - The RPC channel identifier.
     * @param args - Arguments to pass to the RPC handler.
     * @returns A promise resolving with the RPC result.
     */
    invokeServer?<T = any>(rpcName: string, ...args: unknown[]): Promise<T>;
    /**
     * Invokes a client-side RPC on a specific player and returns its result.
     *
     * @typeParam T - The expected return type of the RPC.
     * @param player - The target player instance.
     * @param rpcName - The RPC channel identifier.
     * @param args - Arguments to pass to the RPC handler.
     * @returns A promise resolving with the RPC result.
     */
    invokeClient?<T = any>(player: TPlayer, rpcName: string, ...args: unknown[]): Promise<T>;
    /**
     * Registers a handler for client-initiated RPC calls.
     *
     * @param rpcName - The RPC channel identifier.
     * @param handler - Function to handle incoming RPC requests.
     */
    onRpcClient?(rpcName: string, handler: (...args: unknown[]) => Promise<unknown> | unknown): void;
    /**
     * Registers a handler for server-initiated RPC calls.
     *
     * @param rpcName - The RPC channel identifier.
     * @param handler - Function to handle incoming RPC requests.
     */
    onRpcServer?(rpcName: string, handler: (...args: unknown[]) => Promise<unknown> | unknown): void;
    /**
     * Creates a new WebView instance on the client side.
     *
     * @param id - Unique identifier for the WebView instance.
     * @param url - The URL to load in the WebView.
     * @param focused - Whether the WebView should be focused on creation.
     * @param hidden - Whether the WebView should be hidden initially.
     * @returns A platform‐agnostic {@link IWebView} wrapper.
     */
    createWebview?(id: string | number, url: string, focused: boolean, hidden: boolean): IWebView;
    /**
     * Destroys an existing WebView instance.
     *
     * @param id - The unique identifier of the WebView to destroy.
     */
    destroyWebview?(id: string | number): void;
}

/**
 * Bootstraps and manages the full Aurora application lifecycle:
 * - Scans modules and builds the DI graph
 * - Instantiates controllers up front (to support lifecycle hooks)
 * - Binds controller events to the platform driver via EventBinder
 *
 * Use {@link ApplicationFactory.create} to initialize and obtain the application instance.
 * @category Core
 * @public
 */
declare class ApplicationFactory {
    private readonly platformDriver;
    private readonly applicationRef;
    private readonly moduleWrappers;
    private readonly globalModules;
    private readonly instanceContainer;
    private readonly flowHandler;
    private readonly eventBinder;
    private readonly rpcBinder;
    private readonly plugins;
    private logger;
    private config?;
    private started;
    private closed;
    private debug;
    /**
     * Bootstraps an Aurora application and returns its public interface.
     * @param rootModule The application's root module (entry point)
     * @param platformDriver The platform driver for this runtime
     * @returns A Promise resolving to the IApplication instance
     */
    static create(rootModule: Type, platformDriver: IPlatformDriver, plugins?: AuroraPlugin[]): Promise<IApplication>;
    usePlugins(...plugins: AuroraPlugin[]): this;
    /**
     * Starts the application and binds all controller event handlers.
     */
    start(): Promise<void>;
    /**
     * Shuts down the application and calls shutdown hooks.
     */
    close(signal?: string): Promise<void>;
    /**
     * Resolves an instance from the DI container.
     * @param token The provider token or class
     */
    get<T>(token: Token<T>): Promise<T>;
    /**
     * Binds all controller events (decorated handlers) to the platform driver via EventBinder.
     */
    private bindControllerEvents;
    private bindControllerRpcs;
    /**
     * Internal bootstrap: scans modules, builds the graph, and triggers instantiation.
     * @param rootModuleType The root module class
     */
    private initialize;
    private registerShutdownListeners;
    /**
     * Recursively scans all modules, handles imports/exports and registers global modules.
     */
    private scanModules;
    /**
     * Eagerly instantiates and assigns core services like Logger and Config.
     */
    private initializeCoreServices;
    /**
     * Prints the module graph in a tree format (debug/dev only).
     */
    private logModulesTree;
    private callLifecycle;
    /**
     * Instantiate all providers first, then all controllers.
     */
    private instantiateModules;
    /**
     * Create an instance of the given class, resolving and injecting both
     * constructor-parameter tokens and decorated property tokens.
     *
     * @param targetClass The class to instantiate.
     * @param contextModule The module wrapper providing the DI context.
     * @returns A Promise resolving to a new instance with all dependencies injected.
     */
    private instantiateClass;
    /**
     * Resolves a provider (controller/service) in the DI graph, including global modules.
     * @param token The token/class to resolve
     * @param contextModule The module to start searching from
     * @param seen (Cycle detection)
     */
    private resolveDependency;
    /**
     * Finds the module able to provide the given token.
     * 1. Current module (providers/controllers)
     * 2. Imported modules (recursive, if they export the token)
     * 3. All global modules (@Global)
     */
    private findModuleByProvider;
    /**
     * Finds a provider definition for a token in a given module, including controllers.
     */
    private findProviderDefinition;
}

/**
 * Simple dependency injection container that holds provider instances by token.
 * It allows registering and resolving values or class instances during application runtime.
 *
 * @category Core
 * @public
 */
declare class Container {
    private readonly providers;
    /**
     * Registers a provider instance under the given token.
     * If a provider already exists for this token, it will be overridden.
     *
     * @param token The injection token (class constructor, string, or symbol).
     * @param value The instance or value to associate with the token.
     */
    register<T>(token: Token<T>, value: T): void;
    /**
     * Retrieves the provider instance associated with the given token.
     *
     * @param token The injection token to resolve.
     * @returns The instance or value stored under the token.
     * @throws {Error} If no provider is found for the token.
     */
    resolve<T>(token: Token<T>): T;
    /**
     * Checks whether a provider is registered for the given token.
     *
     * @param token The injection token to check.
     * @returns `true` if a provider exists, `false` otherwise.
     */
    has<T>(token: Token<T>): boolean;
    /**
     * Returns an iterator over all registered provider instances.
     * Can be used for debugging or lifecycle management.
     *
     * @returns Iterable iterator of all stored provider values.
     */
    getInstances(): IterableIterator<unknown>;
}

/**
 * Wraps a module’s metadata and DI state for internal management.
 * Handles providers, controllers, imports, and exports for a single module.
 *
 * @category Core
 * @public
 */
declare class ModuleWrapper {
    readonly type: Type;
    readonly metadata: ModuleMetadata;
    /**
     * Modules imported by this module.
     */
    private readonly _imports;
    /**
     * Controller classes declared in this module.
     */
    private readonly _controllers;
    /**
     * Tokens exported by this module for other modules to consume.
     */
    private readonly _exports;
    /**
     * The DI container instance scoped to this module.
     * Initially holds provider definitions, later replaced with their instantiated values.
     */
    readonly container: Container;
    /**
     * Creates a new ModuleWrapper.
     *
     * @param type The module’s class constructor.
     * @param metadata The metadata extracted from the @Module decorator, including
     *                 imports, controllers, providers, and exports.
     */
    constructor(type: Type, metadata: ModuleMetadata);
    /**
     * Gets the set of modules imported by this module.
     */
    get imports(): Set<ModuleWrapper>;
    /**
     * Gets the set of controller classes declared in this module.
     */
    get controllers(): Set<Type>;
    /**
     * Gets the set of tokens this module exports.
     */
    get exports(): Set<Token>;
    /**
     * Adds an imported module to this module’s import graph.
     *
     * @param importedModule The ModuleWrapper instance to import.
     */
    addImport(importedModule: ModuleWrapper): void;
    /**
     * Determines the DI token for a provider definition.
     * If the provider is a class constructor, the constructor itself is the token;
     * otherwise uses the `provide` property of the Provider object.
     *
     * @param provider The provider definition (class or object).
     * @returns The token under which this provider is registered.
     */
    private getTokenFromProvider;
}

/**
 * Orchestrates the execution pipeline for controller/service methods:
 * - Resolves method parameters (via decorators)
 * - Executes guards if defined
 * - Invokes the decorated method on the instance
 */
declare class ControllerFlowHandler {
    private readonly container;
    private logger;
    constructor(container: Container);
    setLogger(logger: ILogger): void;
    /**
     * Maps the ExecutionContext to an array of arguments for the controller method.
     * @param context The current execution context containing raw arguments.
     * @param event Metadata for the event handler including parameter definitions.
     * @returns An array of arguments to apply to the controller method.
     */
    createArgs(context: ExecutionContext, handler: EventMetadata | RpcMetadata): unknown[];
    canActivate(context: ExecutionContext): Promise<boolean>;
    wrapWithGuardsProxy<T extends object>(instance: T, targetClass: Type): T;
    hasGuards(targetClass: Type): boolean;
}

/**
 * EventBinder attaches decorated controller events to the platform driver.
 *
 * @category Core
 * @public
 */
declare class EventBinder {
    private readonly platformDriver;
    private readonly flowHandler;
    constructor(platformDriver: IPlatformDriver, flowHandler: ControllerFlowHandler);
    /**
     * Binds all controller event handlers for a given set of modules/controllers.
     * @param controllersWithInstances Array of [ControllerClass, controllerInstance]
     */
    bindControllerEvents(controllersWithInstances: [Type, Record<string, unknown>][]): void;
    /**
     * Creates a dispatcher for the event handler method (param injection).
     */
    private createDispatcher;
}

/**
 * The token for the platform-specific configuration loader.
 */
declare const CONFIG_LOADER: unique symbol;
/**
 * Dependency injection token for the config service.
 * Use this symbol to register or retrieve the config instance that
 * handles structured config throughout the application on server-side.
 */
declare const CONFIG_SERVICE: unique symbol;
/**
 * Dependency injection token for the global event handling service.
 * Use this symbol to register or retrieve the service responsible for
 * emitting and listening to application-wide events.
 */
declare const EVENT_SERVICE: unique symbol;
/**
 * Dependency injection token for the global rpc service.
 * Use this symbol to register or retrieve the service responsible for
 * emitting and listening to application-wide rpcs.
 */
declare const RPC_SERVICE: unique symbol;
/**
 * Dependency injection token for the logging service.
 * Use this symbol to register or retrieve the logger instance that
 * handles structured logging throughout the application.
 */
declare const LOGGER_SERVICE: unique symbol;
/**
 * Dependency injection token for the platform driver.
 * Use this symbol to register or retrieve the driver that provides
 * platform-specific APIs and runtime integration.
 */
declare const PLATFORM_DRIVER: unique symbol;
/**
 * Dependency injection token for the WebView service.
 * Use this symbol to register or retrieve the service responsible for
 * creating and managing in-game WebView instances.
 */
declare const WEBVIEW_SERVICE: unique symbol;

/**
 * Factory for creating method decorators that bind controller methods to runtime events.
 *
 * @param type The type of the event (from EventType enum) to listen for.
 * @param name Optional custom event name; defaults to the method name.
 * @param webViewId Optional identifier for targeting a specific WebView instance.
 * @returns A method decorator that registers the decorated method in the controller's event metadata.
 *
 * @throws {Error} If the same method is decorated more than once with an event decorator.
 */
declare function createEventDecorator(type: EventType, name?: string, webViewId?: string | number): MethodDecorator;

/**
 * Method decorator that binds a controller method to the `ON` event type.
 *
 * @param eventName Optional custom event name; if omitted, the method name will be used.
 * @returns A method decorator that registers the decorated method as an event handler
 *          for `EventType.ON` in the controller’s metadata.
 *
 * @example
 * ```ts
 * @Controller()
 * class MyController {
 *   @On('playerJoined')
 *   handlePlayerJoin(data: PlayerData) {
 *     // ...handle player join...
 *   }
 * }
 * ```
 * @public
 */
declare function On(eventName?: string): MethodDecorator;

/**
 * Factory to create parameter decorators for controller event handlers.
 * Each decorator specifies how to resolve a method parameter at runtime.
 *
 * @param type The kind of parameter to inject (from MethodParamType enum).
 * @returns A function that accepts optional data and returns a ParameterDecorator.
 *
 * @public
 */
declare function createParamDecorator(type: MethodParamType): (data?: unknown) => ParameterDecorator;

/**
 * Parameter decorator to inject a specific property from the event payload.
 * It's an alias for `@Payload(key)`.
 *
 * @param propertyKey The key of the property to extract from the payload object.
 * @example
 * ```ts
 * onMoneyTransfer(@Param('amount') amount: number)
 * ```
 */
declare const Param: (data?: unknown) => ParameterDecorator;

/**
 * Injects the event payload into a controller method parameter.
 * Can optionally inject a specific property from the payload if a key is provided.
 *
 * @param propertyKey A key to extract a specific property from the payload object.
 */
declare const Payload: (data?: unknown) => ParameterDecorator;

/**
 * Parameter decorator for injecting the player object associated with an event.
 *
 * @param propertyKey Optional. A key to extract a specific property from the player object (e.g., 'name', 'ip').
 * If not provided, the entire player object is injected.
 * @example
 * ```ts
 * // Injects the entire player object
 * onPlayerEvent(@Player() player: Player)
 *
 * // Injects only the player's name
 * onPlayerEvent(@Player('name') name: string)
 * ```
 */
declare const Player: (data?: unknown) => ParameterDecorator;

declare function createRpcDecorator(type: RpcType, name?: string, webViewId?: string | number): MethodDecorator;

/**
 * Class decorator that marks a class as a controller within the Aurora framework.
 * Controllers will be scanned and instantiated by the ApplicationFactory,
 * and their decorated event-handler methods will be bound to the platform driver.
 *
 * @throws {Error} if applied more than once on the same class.
 * @public
 */
declare function Controller(): ClassDecorator;

/**
 * Class decorator that marks a module as global within the Aurora framework.
 * Global modules are available in every other module without needing to be imported.
 *
 * @throws {Error} if applied more than once on the same class.
 * @public
 */
declare function Global(): ClassDecorator;

/**
 * Decorator to inject dependencies into constructor parameters or class properties.
 *
 * When applied to a parameter, stores the custom injection token for that parameter index.
 * When applied to a property, records the injection token to resolve and assign the dependency after instantiation.
 *
 * @param token The injection token (class constructor, string, or symbol) to resolve from the DI container.
 * @returns A decorator function usable as both a ParameterDecorator and PropertyDecorator.
 * @public
 */
declare function Inject(token: Token): PropertyDecorator & ParameterDecorator;

/**
 * Class decorator that marks a class as injectable into the Aurora DI container.
 * You can optionally specify the provider scope:
 * - `Scope.SINGLETON` (default): one shared instance per application.
 * - `Scope.TRANSIENT`: a new instance for each injection.
 *
 * @param options Optional configuration for this injectable provider.
 * @param options.scope The desired lifetime scope for instances of this class.
 * @throws {Error} If the decorator is applied more than once on the same class.
 * @public
 */
declare function Injectable(options?: InjectableOptions): ClassDecorator;

/**
 * Class decorator that designates a class as a module in the Aurora framework.
 * A module groups related controllers, providers, and imported/exported modules
 * into a cohesive unit for dependency scanning and resolution.
 *
 * @param metadata Configuration object defining:
 *  - `imports`: other modules whose providers/controllers should be available
 *  - `controllers`: controller classes to instantiate and bind
 *  - `providers`: service classes or tokens to register in the DI container
 *  - `exports`: subset of providers/controllers to expose to importing modules
 *
 * @throws {Error}
 *  - If applied more than once to the same class.
 *  - If the metadata contains keys outside of the allowed set (`imports`, `controllers`, `providers`, `exports`).
 * @public
 */
declare function Module(metadata: ModuleMetadata): ClassDecorator;

/**
 * Attaches arbitrary metadata to a class or class member (method/property).
 *
 * @template T
 * @param key - The metadata key, typically a symbol or unique string.
 * @param value - The metadata value to store under the given key.
 * @returns A decorator that applies the metadata via Reflect.defineMetadata.
 */
declare function SetMetadata<T = any>(key: string | symbol, value: T): ClassDecorator & MethodDecorator;

/**
 * Decorator that attaches one or more Guard classes to a class or to a specific method.
 *
 * When applied at the class level, all methods of the class will be protected
 * by the specified guards. When applied to a method, only that method will be protected.
 *
 * @param guards - One or more guard constructors implementing the Guard interface.
 * @returns A decorator usable on classes and methods.
 *
 * @example
 * // Class-level guards
 * @UseGuards(AuthGuard, RoleGuard)
 * class MyController { ... }
 *
 * // Event-level guards
 * @UseGuards(AuthGuard, RoleGuard)
 * class MyController {
 *   @UseGuards(MyGuard)
 *   @On()
 *   onMyEvent() { ... }
 * }
 *
 * // Method-level guards
 * class MyService {
 *   @UseGuards(PermissionsGuard)
 *   sensitiveOperation() { ... }
 * }
 */
declare function UseGuards(...guards: Type<Guard>[]): ClassDecorator & MethodDecorator;

/**
 * Union of all normalized providers: guarantees the presence of `provide`.
 */
type NormalizedProvider<T = unknown> = ClassProvider<T> | ValueProvider<T> | FactoryProvider<T>;
/**
 * Takes either:
 *  - a raw Type<T> (class constructor), or
 *  - a Provider<T> object (with useClass/useValue/useFactory)
 * and returns a NormalizedProvider<T> that always has a `provide` property.
 */
declare function normalizeProvider<T = unknown>(provider: Provider<T> | Type<T>): NormalizedProvider<T>;
/**
 * Determines the injection scope (Singleton or Transient):
 *  - Factory providers default to SINGLETON.
 *  - Class and value providers inherit the scope metadata from @Injectable.
 */
declare function getProviderScope(provider: Provider<unknown> | Type<unknown>): Scope;

/**
 * Returns a human-readable identifier for a DI token.
 * - If the token is a class constructor, returns its `name`.
 * - Otherwise, returns `String(token)`.
 *
 * @param token The injection token (constructor, string, symbol, or provider).
 * @returns A simple string name for use in logs or error messages.
 * @public
 */
declare function getTokenName(token: unknown): string;
/**
 * Produces a detailed string representation of a DI token or provider definition.
 * - Class constructors → their `name`.
 * - Symbols → `symbol.toString()`.
 * - Provider objects:
 *   - If it has a `provide` key, recurses on that token.
 *   - If it has `useClass`, shows `[useClass: ClassName]`.
 *   - If it has `useValue`, shows `[useValue: <type>]`.
 * - Fallback → `String(token)`.
 *
 * @param token The injection token or provider object to stringify.
 * @returns A descriptive string for debugging or error output.
 * @public
 */
declare function tokenToString(token: unknown): string;

export { ApplicationFactory, type ArgumentMetadata, type AuroraPlugin, type BaseParameter, CONFIG_LOADER, CONFIG_SERVICE, type ClassProvider, Container, Controller, ControllerFlowHandler, EVENT_SERVICE, EventBinder, type EventMetadata, EventType, type ExecutionContext, type FactoryProvider, Global, type Guard, type IApplication, type IConfigLoader, type IConfigService, type ILogger, type IPlatformDriver, type IWebView, Inject, Injectable, type InjectableOptions, LOGGER_SERVICE, MethodParamType, type MethodParameter, Module, type ModuleMetadata, ModuleWrapper, type NormalizedProvider, On, type OnAppInit, type OnAppShutdown, type OnAppStarted, PLATFORM_DRIVER, Param, type ParamParameter, Payload, type PayloadParameter, Player, type PlayerParameter, type Provider, RPC_SERVICE, type RpcMetadata, RpcType, Scope, SetMetadata, type Token, type Type, UseGuards, type ValueProvider, WEBVIEW_SERVICE, WebViewEvents, createEventDecorator, createParamDecorator, createRpcDecorator, getProviderScope, getTokenName, normalizeProvider, tokenToString };