Merge pull request 'Server/Client middlewares + JSDoc' (#6) from unstable into dev

Reviewed-on: #6

browser/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entityseven/rage-fw-browser",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "main": "dist/index.js",
     "types": "dist/src/index.d.ts",
     "files": [
@@ -14,16 +14,19 @@
         "@entityseven/rage-fw-rpc": "latest"
     },
     "peerDependencies": {
-        "@ragempcommunity/types-cef": "^2.1.8",
-        "@entityseven/rage-fw-shared-types": "workspace:^"
+        "@entityseven/rage-fw-shared-types": "workspace:^",
+        "@ragempcommunity/types-cef": "^2.1.8"
     },
     "description": "RageFW CEF side",
     "keywords": [],
     "author": "SashaGoncharov19",
-    "contributors": [{
-        "name": "rilaxik",
-        "email": "dev.rilaxik@gmail.com",
-        "url": "https://github.com/rilaxik"
-    }],
-    "license": "MIT"
+    "contributors": [
+        {
+            "name": "rilaxik",
+            "email": "dev.rilaxik@gmail.com",
+            "url": "https://github.com/rilaxik"
+        }
+    ],
+    "license": "MIT",
+    "gitHead": "ffd542c1deddb3033e16e0dae7557313ae09b05f"
 }

browser/src/core/browser.ts

@@ -7,21 +7,43 @@ import {
     RageFW_ServerEvent,
 } from '../types'
 
+/** Browser-side interactions */
 export class Browser extends Helper {
     constructor() {
         super()
     }
 
+    /**
+     * Setter. Enables console debug logs for events
+     */
     set debugLogs(debug: boolean) {
         this.debugLogs_ = debug
     }
 
+    /**
+     * Setter. Provides an ability to specify custom logger function to get special formatting. Using this enables ``debugLogs``
+     */
     set customLogger(
         fn: (method: string, eventName: string, ...args: unknown[]) => unknown,
     ) {
         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 +59,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 +79,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 +113,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 +147,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

browser/src/core/rpc.ts

@@ -1,7 +1,6 @@
 import { Rpc } from '@entityseven/rage-fw-rpc'
 
 export const rpc = new Rpc({
-    forceBrowserDevMode:
-        process.env.RageFW_forceBrowserDevMode === 'true' ?? false,
+    forceBrowserDevMode: process.env.RageFW_forceBrowserDevMode === 'true',
     debugLogs: false,
 })

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

client/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entityseven/rage-fw-client",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "main": "dist/index.js",
     "types": "dist/src/index.d.ts",
     "files": [
@@ -14,17 +14,19 @@
         "@entityseven/rage-fw-rpc": "latest"
     },
     "peerDependencies": {
-        "@ragempcommunity/types-client": "^2.1.8",
-        "@entityseven/rage-fw-shared-types": "workspace:^"
+        "@entityseven/rage-fw-shared-types": "workspace:^",
+        "@ragempcommunity/types-client": "^2.1.8"
     },
     "description": "RageFW Client side",
     "keywords": [],
     "author": "SashaGoncharov19",
-    "contributors": [{
-        "name": "rilaxik",
-        "email": "dev.rilaxik@gmail.com",
-        "url": "https://github.com/rilaxik"
-    }],
+    "contributors": [
+        {
+            "name": "rilaxik",
+            "email": "dev.rilaxik@gmail.com",
+            "url": "https://github.com/rilaxik"
+        }
+    ],
     "license": "MIT",
-    "gitHead": "053e4fd12aa120d53e11e0d2009c0df78c1a2ad0"
+    "gitHead": "ffd542c1deddb3033e16e0dae7557313ae09b05f"
 }

client/src/core/client.ts

@@ -1,20 +1,77 @@
 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>,
+        options?: {
+            middlewares?: T.RageFW_MiddlewareOptions<EventName>
+        },
     ): Client {
         rpc.register<
             Parameters<typeof callback>,
-            ReturnType<typeof callback>,
+            ReturnType<typeof callback> | Promise<unknown>,
             EventName
-        >(eventName, async (...data) => await callback(...data))
+        >(eventName, async (...data) => {
+            if (!options?.middlewares) return await callback(...data)
+
+            await Middleware.process(options.middlewares, callback, data)
+        })
 
         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 {

client/src/core/index.ts

@@ -1,4 +1,5 @@
 export * from './client'
 export * from './logger'
+export * from './middleware'
 export * from './player'
 export * from './rpc'

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

client/src/core/middleware.ts

@@ -0,0 +1,54 @@
+import type * as T from '../types'
+
+export class Middleware {
+    constructor() {}
+
+    private static async execute<EventName extends T.RageFW_ClientEvent>(
+        middlewares: T.RageFW_MiddlewareFunction<EventName>[],
+        args: T.RageFW_ClientArgs<EventName>,
+    ): Promise<T.RageFW_MiddlewareResponseInternal> {
+        for (let i = 0; i < middlewares.length; i++) {
+            const result = await middlewares[i](...args)
+
+            if (typeof result === 'boolean' && !result)
+                return { success: result, id: i }
+            if (typeof result !== 'boolean' && !result.success)
+                return { ...result, id: i }
+        }
+
+        return {
+            success: true,
+        }
+    }
+
+    public static async process<EventName extends T.RageFW_ClientEvent>(
+        middlewareOptions: T.RageFW_MiddlewareOptions<EventName>,
+        callback: T.RageFW_ClientCallback<EventName>,
+        args: T.RageFW_ClientArgs<EventName>,
+    ) {
+        if (Array.isArray(middlewareOptions)) {
+            const middlewaresResponse = await Middleware.execute(
+                middlewareOptions,
+                args,
+            )
+
+            if (middlewaresResponse.success) return await callback(...args)
+        } else {
+            const middlewaresResponse = await Middleware.execute(
+                middlewareOptions.executables,
+                args,
+            )
+
+            if (middlewaresResponse.success) {
+                return await callback(...args)
+            } else {
+                middlewareOptions.onError(
+                    middlewaresResponse.message ??
+                        'Middleware with id ' +
+                            middlewaresResponse.id +
+                            ' failed',
+                )
+            }
+        }
+    }
+}

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 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

client/src/index.ts

@@ -1,10 +1,22 @@
 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,
 }

client/src/types/index.ts

@@ -1,3 +1,4 @@
-export * from './client'
-export * from './server'
 export * from './browser'
+export * from './client'
+export * from './middleware'
+export * from './server'

client/src/types/middleware.ts

@@ -0,0 +1,26 @@
+import type * as T from './client'
+
+export type RageFW_MiddlewareResponse =
+    | {
+          success: boolean
+          message?: string
+      }
+    | boolean
+
+export type RageFW_MiddlewareResponseInternal = {
+    success: boolean
+    message?: string
+    id?: number
+}
+
+export type RageFW_MiddlewareFunction<EventName extends T.RageFW_ClientEvent> =
+    (
+        ...args: T.RageFW_ClientArgs<EventName>
+    ) => Promise<RageFW_MiddlewareResponse>
+
+export type RageFW_MiddlewareOptions<EventName extends T.RageFW_ClientEvent> =
+    | RageFW_MiddlewareFunction<EventName>[]
+    | {
+          executables: RageFW_MiddlewareFunction<EventName>[]
+          onError: (error: string) => unknown
+      }

lerna.json

@@ -1,5 +1,5 @@
 {
     "$schema": "node_modules/lerna/schemas/lerna-schema.json",
-    "version": "0.2.5",
+    "version": "0.2.1-0.2.0-alpha.2.0",
     "npmClient": "pnpm"
 }

package.json

@@ -5,10 +5,10 @@
     "build": "lerna run build",
     "lint": "eslint --c .eslintrc.yaml --ext .ts client/ server/ shared-types/",
 
-    "rebuild:cef": "cd cef && pnpm build",
+    "rebuild:browser": "cd browser && pnpm build",
     "rebuild:client": "cd client && pnpm build",
     "rebuild:server": "cd server && pnpm build",
-    "rebuild": "pnpm rebuild:cef && pnpm rebuild:client && pnpm rebuild:server"
+    "rebuild": "pnpm rebuild:browser && pnpm rebuild:client && pnpm rebuild:server"
   },
   "dependencies": {
     "@microsoft/api-extractor": "^7.47.0",

server/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entityseven/rage-fw-server",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "main": "dist/index.js",
     "types": "dist/src/index.d.ts",
     "files": [
@@ -14,17 +14,19 @@
         "@entityseven/rage-fw-rpc": "latest"
     },
     "peerDependencies": {
-        "@ragempcommunity/types-server": "^2.1.8",
-        "@entityseven/rage-fw-shared-types": "workspace:^"
+        "@entityseven/rage-fw-shared-types": "workspace:^",
+        "@ragempcommunity/types-server": "^2.1.8"
     },
     "description": "RageFW Server side",
     "keywords": [],
     "author": "SashaGoncharov19",
-    "contributors": [{
-        "name": "rilaxik",
-        "email": "dev.rilaxik@gmail.com",
-        "url": "https://github.com/rilaxik"
-    }],
+    "contributors": [
+        {
+            "name": "rilaxik",
+            "email": "dev.rilaxik@gmail.com",
+            "url": "https://github.com/rilaxik"
+        }
+    ],
     "license": "MIT",
-    "gitHead": "053e4fd12aa120d53e11e0d2009c0df78c1a2ad0"
+    "gitHead": "ffd542c1deddb3033e16e0dae7557313ae09b05f"
 }

server/src/core/index.ts

@@ -1,4 +1,5 @@
 export * from './logger'
+export * from './middleware'
 export * from './player'
 export * from './rpc'
 export * from './server'

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

server/src/core/middleware.ts

@@ -0,0 +1,54 @@
+import type * as T from '../types'
+
+export class Middleware {
+    constructor() {}
+
+    private static async execute<EventName extends T.RageFW_ServerEvent>(
+        middlewares: T.RageFW_MiddlewareFunction<EventName>[],
+        args: T.RageFW_ServerArgs<EventName>,
+    ): Promise<T.RageFW_MiddlewareResponseInternal> {
+        for (let i = 0; i < middlewares.length; i++) {
+            const result = await middlewares[i](...args)
+
+            if (typeof result === 'boolean' && !result)
+                return { success: result, id: i }
+            if (typeof result !== 'boolean' && !result.success)
+                return { ...result, id: i }
+        }
+
+        return {
+            success: true,
+        }
+    }
+
+    public static async process<EventName extends T.RageFW_ServerEvent>(
+        middlewareOptions: T.RageFW_MiddlewareOptions<EventName>,
+        callback: T.RageFW_ServerCallback<EventName>,
+        args: T.RageFW_ServerArgs<EventName>,
+    ) {
+        if (Array.isArray(middlewareOptions)) {
+            const middlewaresResponse = await Middleware.execute(
+                middlewareOptions,
+                args,
+            )
+
+            if (middlewaresResponse.success) return await callback(...args)
+        } else {
+            const middlewaresResponse = await Middleware.execute(
+                middlewareOptions.executables,
+                args,
+            )
+
+            if (middlewaresResponse.success) {
+                return await callback(...args)
+            } else {
+                middlewareOptions.onError(
+                    middlewaresResponse.message ??
+                        'Middleware with id ' +
+                            middlewaresResponse.id +
+                            ' failed',
+                )
+            }
+        }
+    }
+}

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

server/src/core/server.ts

@@ -1,20 +1,77 @@
 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>,
+        options?: {
+            middlewares?: T.RageFW_MiddlewareOptions<EventName>
+        },
     ): Server {
         rpc.register<
             Parameters<typeof callback>,
-            ReturnType<typeof callback>,
+            ReturnType<typeof callback> | Promise<unknown>,
             EventName
-        >(eventName, async (...data) => await callback(...data))
+        >(eventName, async (...data) => {
+            if (!options?.middlewares) return await callback(...data)
+
+            await Middleware.process(options.middlewares, callback, data)
+        })
 
         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 {

server/src/index.ts

@@ -1,11 +1,23 @@
 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,
 }
 

server/src/types/index.ts

@@ -1,3 +1,4 @@
-export * from './client'
-export * from './server'
 export * from './browser'
+export * from './client'
+export * from './middleware'
+export * from './server'

server/src/types/middleware.ts

@@ -0,0 +1,26 @@
+import type * as T from './server'
+
+export type RageFW_MiddlewareResponse =
+    | {
+          success: boolean
+          message?: string
+      }
+    | boolean
+
+export type RageFW_MiddlewareResponseInternal = {
+    success: boolean
+    message?: string
+    id?: number
+}
+
+export type RageFW_MiddlewareFunction<EventName extends T.RageFW_ServerEvent> =
+    (
+        ...args: T.RageFW_ServerArgs<EventName>
+    ) => Promise<RageFW_MiddlewareResponse>
+
+export type RageFW_MiddlewareOptions<EventName extends T.RageFW_ServerEvent> =
+    | RageFW_MiddlewareFunction<EventName>[]
+    | {
+          executables: RageFW_MiddlewareFunction<EventName>[]
+          onError: (error: string) => unknown
+      }

shared-types/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entityseven/rage-fw-shared-types",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "types": "types/types/index.d.ts",
     "files": [
         "types/**/*"
@@ -8,5 +8,5 @@
     "author": "SashaGoncharov19",
     "license": "MIT",
     "type": "module",
-    "gitHead": "053e4fd12aa120d53e11e0d2009c0df78c1a2ad0"
+    "gitHead": "ffd542c1deddb3033e16e0dae7557313ae09b05f"
 }