entityseven/rage-framework
2
2
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Server/Client middlewares + JSDoc #6

Merged
rilaxik merged 8 commits from unstable into dev 2024-10-30 16:21:29 +00:00
Conversation 0 Commits 8 Files Changed 26 +358 -6
10 changed files with 358 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit cd27764a30 - Show all commits

85
browser/src/core/browser.ts
View File

@ -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 extends T.RageFW_BrowserEvent>(
eventName: EventName,
callback: T.RageFW_BrowserCallback<EventName>,
@ -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 extends T.RageFW_BrowserEvent>(
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 extends T.RageFW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> 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 extends T.RageFW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> 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 extends T.RageFW_ClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true

7
browser/src/index.ts
View File

@ -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 () => {

49
client/src/core/client.ts
View File

@ -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 extends T.RageFW_ClientEvent>(
eventName: EventName,
callback: T.RageFW_ClientCallback<EventName>,
@ -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 extends T.RageFW_ClientEvent>(
eventName: EventName,
): Client {

33
client/src/core/logger.ts
View File

@ -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(' ')}`,
)
}
}

61
client/src/core/player.ts
View File

@ -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 extends keyof T.RageFW_ICustomClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> 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 extends T.RageFW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> 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 extends T.RageFW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true

10
client/src/index.ts
View File

@ -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,
}

19
server/src/core/logger.ts
View File

@ -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(' '))
}

41
server/src/core/player.ts
View File

@ -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<EventName extends T.RageFW_ClientEvent>(
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<EventName extends T.RageFW_BrowserEvent>(
player: PlayerMp,
eventName: EventName,

49
server/src/core/server.ts
View File

@ -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 extends T.RageFW_ServerEvent>(
eventName: EventName,
callback: T.RageFW_ServerCallback<EventName>,
@ -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 extends T.RageFW_ServerEvent>(
eventName: EventName,
): Server {

10
server/src/index.ts
View File

@ -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,
}