From cd27764a30fef44a19912dfa5f10f326f9d3314d Mon Sep 17 00:00:00 2001 From: Danya H Date: Wed, 30 Oct 2024 15:27:22 +0000 Subject: [PATCH] jsdoc --- browser/src/core/browser.ts | 85 +++++++++++++++++++++++++++++++++++++ browser/src/index.ts | 7 +++ client/src/core/client.ts | 49 +++++++++++++++++++++ client/src/core/logger.ts | 33 +++++++++++--- client/src/core/player.ts | 61 ++++++++++++++++++++++++++ client/src/index.ts | 10 +++++ server/src/core/logger.ts | 19 +++++++++ server/src/core/player.ts | 41 ++++++++++++++++++ server/src/core/server.ts | 49 +++++++++++++++++++++ server/src/index.ts | 10 +++++ 10 files changed, 358 insertions(+), 6 deletions(-) diff --git a/browser/src/core/browser.ts b/browser/src/core/browser.ts index de7efdc..afde257 100644 --- a/browser/src/core/browser.ts +++ b/browser/src/core/browser.ts @@ -7,6 +7,7 @@ import { RageFW_ServerEvent, } from '../types' +/** Browser-side interactions */ export class Browser extends Helper { constructor() { super() @@ -22,6 +23,21 @@ export class Browser extends Helper { this.customLogger_ = fn } + /** + * Registers a browser event with an associated callback + * + * @param eventName - The name of the event to register + * @param callback - The callback function to be executed when the event is triggered + * @returns {Browser} The current browser instance, enabling method chaining + * + * @example + * // Registering an event + * fw.event.register("showNotification", (message, color) => { + * // do something + * }) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public register( eventName: EventName, callback: T.RageFW_BrowserCallback, @@ -37,6 +53,18 @@ export class Browser extends Helper { return this } + /** + * Unregisters a browser event, removing the associated callback + * + * @param eventName - The name of the event to unregister + * @returns {Browser} The current browser instance, enabling method chaining + * + * @example + * // Unregistering an event + * fw.event.unregister("showNotification") + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public unregister( eventName: EventName, ): Browser { @@ -45,6 +73,25 @@ export class Browser extends Helper { return this } + /** + * Triggers a browser event from the browser with arguments from shared types + * + * Formerly known as ``call`` or ``emit`` + * + * @param eventName - The name of the browser event to trigger + * @param [args] - Arguments for the browser event, if present + * @returns {Promise} resolving to the browser's response for the event + * + * @example + * // Triggering a browser event without arguments + * fw.event.trigger("browserEventName") + * + * @example + * // Triggering a browser event with arguments + * fw.event.trigger("browserEventName", ["message to me"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async trigger( eventName: EventName, ...args: T._BrowserEventHasArgs extends true @@ -60,6 +107,25 @@ export class Browser extends Helper { >(eventName, args) } + /** + * Triggers a server event from the browser with arguments from shared types + * + * Formerly known as ``callServer`` or ``emitServer`` + * + * @param eventName - The name of the server event to trigger + * @param [args] - Arguments for the server event, if present + * @returns {Promise} resolving to the server's response for the event + * + * @example + * // Triggering a server event without arguments + * fw.event.triggerServer("serverEventName") + * + * @example + * // Triggering a server event with arguments + * fw.event.triggerServer("serverEventName", ["message to server"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerServer( eventName: EventName, ...args: T._ServerEventHasArgs extends true @@ -75,6 +141,25 @@ export class Browser extends Helper { >(eventName, args) } + /** + * Triggers a client event from the browser with arguments from shared types + * + * Formerly known as ``callClient`` or ``emitClient`` + * + * @param eventName - The name of the client event to trigger + * @param [args] - Arguments for the client event, if present + * @returns {Promise} resolving to the client's response for the event + * + * @example + * // Triggering a client event without arguments + * fw.event.triggerClient("clientEventName") + * + * @example + * // Triggering a client event with arguments + * fw.event.triggerClient("clientEventName", ["message to client"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerClient( eventName: EventName, ...args: T._ClientEventHasArgs extends true diff --git a/browser/src/index.ts b/browser/src/index.ts index ad01249..9cab4e1 100644 --- a/browser/src/index.ts +++ b/browser/src/index.ts @@ -1,7 +1,14 @@ import { Browser, rpc } from './core' +/** + * Package used on a browser-side of your Rage:MP Server + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ export const fw = { + /** Browser-side interactions */ event: new Browser(), + /** ``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance */ rpc, } ;(async () => { diff --git a/client/src/core/client.ts b/client/src/core/client.ts index 8cc45a7..bb1ba4a 100644 --- a/client/src/core/client.ts +++ b/client/src/core/client.ts @@ -2,7 +2,44 @@ import { rpc } from './rpc' import { Middleware } from './middleware' import type * as T from '../types' +/** Client-side interactions */ export class Client { + /** + * Registers a client event with an associated callback + * + * @param eventName - The name of the event to register + * @param callback - The callback function to be executed when the event is triggered + * @param [options] - Optional settings for callback execution + * @param [options.middlewares] - Middleware functions to be checked before the callback executes + * @returns {Client} The current client instance, enabling method chaining + * + * @example + * // Registering an event + * fw.event.register("playerDeath", (player, reason, killer) => { + * fw.system.log.info(player, reason, killer) + * }) + * + * @example + * // Registering an event with middlewares + * fw.event.register("playerDeath", (player, reason, killer) => { + * fw.system.log.info(player, reason, killer) + * }, { + * middlewares: [ignoreSuicide] // <- your middlewares here + * }) + * + * // or + * + * fw.event.register("playerDeath", (player, reason, killer) => { + * fw.system.log.info(player, reason, killer) + * }, { + * middlewares: { + * executables: [ignoreSuicide], // <- your middlewares here + * onError: (msg) => fw.system.log.info(`${player.socialClub} has commited suicide`) + * } + * }) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public register( eventName: EventName, callback: T.RageFW_ClientCallback, @@ -23,6 +60,18 @@ export class Client { return this } + /** + * Unregisters a client event, removing the associated callback + * + * @param eventName - The name of the event to unregister + * @returns {Client} The current client instance, enabling method chaining + * + * @example + * // Unregistering an event + * fw.event.unregister("playerDeath") + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public unregister( eventName: EventName, ): Client { diff --git a/client/src/core/logger.ts b/client/src/core/logger.ts index 99c3fe6..16dc37e 100644 --- a/client/src/core/logger.ts +++ b/client/src/core/logger.ts @@ -1,19 +1,40 @@ +/** + * Used to log to a client in-game console + */ export class Logger { - public error(...message: unknown[]) { - mp.console.logError( - `[${new Date().toLocaleTimeString()}] [ERROR] ${message.join(' ')}`, + /** + * Informational logs. Colored in white + * + * @example + * fw.system.log.info('some information to be logged') + */ + public info(...message: unknown[]) { + mp.console.logInfo( + `[${new Date().toLocaleTimeString()}] [INFO] ${message.join(' ')}`, ) } + /** + * Warning logs. Colored in yellow + * + * @example + * fw.system.log.warn('warning message') + */ public warn(...message: unknown[]) { mp.console.logWarning( `[${new Date().toLocaleTimeString()}] [WARN] ${message.join(' ')}`, ) } - public info(...message: unknown[]) { - mp.console.logInfo( - `[${new Date().toLocaleTimeString()}] [INFO] ${message.join(' ')}`, + /** + * Error logs. Colored in red + * + * @example + * fw.system.log.info('some error information') + */ + public error(...message: unknown[]) { + mp.console.logError( + `[${new Date().toLocaleTimeString()}] [ERROR] ${message.join(' ')}`, ) } } diff --git a/client/src/core/player.ts b/client/src/core/player.ts index e4949f0..40b3589 100644 --- a/client/src/core/player.ts +++ b/client/src/core/player.ts @@ -1,14 +1,37 @@ import { rpc } from './rpc' import type * as T from '../types' +/** Handles event manipulations that require player to be present in context */ export class Player { private _browser: BrowserMp | undefined = undefined + /** + * Setter. Also shares browser with ``rage-fw-rpc`` + */ set browser(browser: BrowserMp) { this._browser = browser rpc.browser = browser } + /** + * Triggers a client event from the client with arguments from shared types + * + * Formerly known as ``call`` or ``emit`` + * + * @param eventName - The name of the client event to trigger + * @param [args] - Arguments for the client event, if present + * @returns {Promise} resolving to the client's response for the event + * + * @example + * // Triggering a client event without arguments + * fw.player.trigger("clientEventName") + * + * @example + * // Triggering a client event with arguments + * fw.player.trigger("clientEventName", ["message to me"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async trigger( eventName: EventName, ...args: T._ClientEventHasArgs extends true @@ -22,6 +45,25 @@ export class Player { >(eventName, args) } + /** + * Triggers a server event from the client with arguments from shared types + * + * Formerly known as ``callServer`` or ``emitServer`` + * + * @param eventName - The name of the server event to trigger + * @param [args] - Arguments for the server event, if present + * @returns {Promise} resolving to the server's response for the event + * + * @example + * // Triggering a server event without arguments + * fw.player.triggerServer("serverEventName") + * + * @example + * // Triggering a server event with arguments + * fw.player.triggerServer("serverEventName", ["message to server"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerServer( eventName: EventName, ...args: T._ServerEventHasArgs extends true @@ -35,6 +77,25 @@ export class Player { >(eventName, args) } + /** + * Triggers a browser event from the client with arguments from shared types + * + * Formerly known as ``callBrowser`` or ``emitBrowser`` + * + * @param eventName - The name of the browser event to trigger + * @param [args] - Arguments for the browser event, if present + * @returns {Promise} resolving to the browser's response for the event + * + * @example + * // Triggering a browser event without arguments + * fw.player.triggerBrowser("browserEventName") + * + * @example + * // Triggering a browser event with arguments + * fw.player.triggerBrowser("browserEventName", ["message to browser"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerBrowser( eventName: EventName, ...args: T._BrowserEventHasArgs extends true diff --git a/client/src/index.ts b/client/src/index.ts index 553e7a2..4a21240 100644 --- a/client/src/index.ts +++ b/client/src/index.ts @@ -2,11 +2,21 @@ import { Client, Logger, Player, rpc } from './core' export type { RageFW_MiddlewareFunction } from './types' +/** + * Package used on a client-side of your Rage:MP Server + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ export const fw = { + /** Client-side interactions */ event: new Client(), + /** Handles event manipulations that require player to be present in context */ player: new Player(), + /** Handles functions used to interact with the client environment */ system: { + /** Used to log in a client in-game console */ log: new Logger(), }, + /** ``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance */ rpc, } diff --git a/server/src/core/logger.ts b/server/src/core/logger.ts index bd656ab..36ed664 100644 --- a/server/src/core/logger.ts +++ b/server/src/core/logger.ts @@ -2,6 +2,7 @@ import winston, { format } from 'winston' const { timestamp, printf, colorize } = format +/** Used to log in a server console */ export class Logger { private format = printf(({ message, level, timestamp }) => { return `[${new Date(timestamp).toLocaleTimeString()}] [${level}]: ${message}` @@ -23,14 +24,32 @@ export class Logger { ), }) + /** + * Informational logs. Colored in white + * + * @example + * fw.system.log.info('some information to be logged') + */ public info(...message: unknown[]) { this.systemLogger.info(message.join(' ')) } + /** + * Warning logs. Colored in yellow + * + * @example + * fw.system.log.warn('warning message') + */ public warn(...message: unknown[]) { this.systemLogger.warn(message.join(' ')) } + /** + * Error logs. Colored in red + * + * @example + * fw.system.log.info('some error information') + */ public error(...message: unknown[]) { this.systemLogger.error(message.join(' ')) } diff --git a/server/src/core/player.ts b/server/src/core/player.ts index 571fd1f..50c539f 100644 --- a/server/src/core/player.ts +++ b/server/src/core/player.ts @@ -1,7 +1,28 @@ import { rpc } from './rpc' import type * as T from '../types' +/** Handles event manipulations that require player to be present in context */ export class Player { + /** + * Triggers a client event from the server with arguments from shared types + * + * Formerly known as ``callClient`` or ``emitClient`` + * + * @param {PlayerMp} player - Player object as an event target + * @param eventName - The name of the client event to trigger + * @param [args] - Arguments for the client event, if present + * @returns {Promise} resolving to the client's response for the event + * + * @example + * // Triggering a client event without arguments + * fw.player.triggerClient("clientEventName") + * + * @example + * // Triggering a client event with arguments + * fw.player.triggerClient("clientEventName", ["message to client"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerClient( player: PlayerMp, eventName: EventName, @@ -12,6 +33,26 @@ export class Player { return await rpc.callClient(player, eventName, args) } + /** + * Triggers a browser event from the server with arguments from shared types + * + * Formerly known as ``callBrowser`` or ``emitBrowser`` + * + * @param {PlayerMp} player - Player object as an event target + * @param eventName - The name of the browser event to trigger + * @param [args] - Arguments for the browser event, if present + * @returns {Promise} resolving to the browser's response for the event + * + * @example + * // Triggering a browser event without arguments + * fw.player.triggerBrowser("browserEventName") + * + * @example + * // Triggering a browser event with arguments + * fw.player.triggerBrowser("browserEventName", ["message to browser"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public async triggerBrowser( player: PlayerMp, eventName: EventName, diff --git a/server/src/core/server.ts b/server/src/core/server.ts index 8d2582c..428e23a 100644 --- a/server/src/core/server.ts +++ b/server/src/core/server.ts @@ -2,7 +2,44 @@ import { rpc } from './rpc' import { Middleware } from './middleware' import type * as T from '../types' +/** Server-side interactions */ export class Server { + /** + * Registers a server event with an associated callback + * + * @param eventName - The name of the event to register + * @param callback - The callback function to be executed when the event is triggered + * @param [options] - Optional settings for callback execution + * @param [options.middlewares] - Middleware functions to be checked before the callback executes + * @returns {Server} The current server instance, enabling method chaining + * + * @example + * // Registering an event + * fw.event.register("playerJoin", (player) => { + * fw.system.log.info(`${player.socialClub} has joined the game`) + * }) + * + * @example + * // Registering an event with middlewares + * fw.event.register("playerJoin", (player) => { + * fw.system.log.info(`${player.name} has joined the game`) + * }, { + * middlewares: [ignoreBots] // <- your middlewares here + * }) + * + * // or + * + * fw.event.register("playerJoin", (player) => { + * fw.system.log.info(`${player.socialClub} has joined the game`) + * }, { + * middlewares: { + * executables: [ignoreBots], // <- your middlewares here + * onError: (msg) => fw.system.log.info(`[BOT] ${player.socialClub} has joined the game`) + * } + * }) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public register( eventName: EventName, callback: T.RageFW_ServerCallback, @@ -23,6 +60,18 @@ export class Server { return this } + /** + * Unregisters a server event, removing the associated callback + * + * @param eventName - The name of the event to unregister + * @returns {Server} The current server instance, enabling method chaining + * + * @example + * // Unregistering an event + * fw.event.unregister("playerJoin") + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ public unregister( eventName: EventName, ): Server { diff --git a/server/src/index.ts b/server/src/index.ts index 54a7c0c..e52728c 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -2,12 +2,22 @@ import { Logger, Player, Server, rpc } from './core' export type { RageFW_MiddlewareFunction } from './types' +/** + * Package used on a server-side of your Rage:MP Server + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ export const fw = { + /** Server-side interactions */ event: new Server(), + /** Handles event manipulations that require player to be present in context */ player: new Player(), + /** Handles functions used to interact with the client environment */ system: { + /** Used to log in a server console */ log: new Logger(), }, + /** ``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance */ rpc, }