updated descriptions

2024-10-30 15:27:00 +00:00 · 2024-10-30 15:27:00 +00:00 · c4ef099b61
commit c4ef099b61
parent e1a0a6be2f
1 changed files with 236 additions and 87 deletions
--- a/Docs%400.2.0.md
+++ b/Docs%400.2.0.md
@ -29,16 +29,16 @@ return true /*Promise<boolean>*/
 })
 ```

-## Server
+# Server
 Package used on a server-side of your Rage:MP Server

-### Usage
+## Usage
 ```ts
 import { fw } from '@entityseven/rage-fw-server'
 ```
 Only usable in server environment. For usage in [Client](#client) and [Browser](#browser) refer to their sections

-### Declaration
+## Declaration
 ```ts
 fw = {
    event: Server,
@ -51,78 +51,105 @@ fw = {
 ```
 Further documentation will describe the fields included in ``fw``

-### Server
-Handles event manipulations that do not require player to be present in context
+## Server
+Server-side interactions

-#### register
-Registers server event
+### register
+Registers a server event with an associated callback
 ```ts
-fw.event.register('serverEventName', ([arg1, arg2]) => {
-    // your logic here
+fw.event.register("playerJoin", (player) => {
+    // do something
+})
+
+// Registering an event with middlewares
+fw.event.register("playerJoin", (player) => {
+    // do something
+}, {
+    middlewares: [...] // <- your middlewares here
+})
+
+// or
+
+fw.event.register("playerJoin", (player) => {
+    // do something
+}, {
+    middlewares: {
+        executables: [...], // <- your middlewares here
+        onError: (msg) => void msg // <- error handling here
+    }
 })
 ```

-#### unregister
-Unregisters server event
+### unregister
+Unregisters a server event, removing the associated callback
 ```ts
-fw.event.unregister('serverEventName')
+fw.event.unregister("playerJoin")
 ```

-#### trigger
+### trigger
 Triggers registered server event. Formerly known as ``call`` or ``emit``
 ```ts
 fw.event.trigger('serverEventName', ['arg1', 2])
 ```

-### Player
+## Player
 Handles event manipulations that require player to be present in context

-#### triggerClient
-Triggers registered client event with passed arguments. Formerly known as ``callClient`` or ``emitClient``
+### triggerClient
+Triggers a client event from the server with arguments from shared types. Formerly known as ``callClient`` or ``emitClient``
 ```ts
-fw.player.triggerClient('clientEventName', ['arg1', 2])
+// without args
+fw.player.triggerClient("clientEventName")
+// with args
+fw.player.triggerClient("clientEventName", ["message to client"])
 ```

-#### triggerBrowser
-Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser``
+### triggerBrowser
+Triggers a browser event from the server with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser``
 ```ts
-fw.player.triggerBrowser('cefEventName', ['arg1', 2])
+// without args
+fw.player.triggerBrowser("browserEventName")
+// with args
+fw.player.triggerBrowser("browserEventName", ["message to browser"])
 ```

-### System
+## System
 Handles functions used to interact with system environment

-#### Logger
-Used to log in a server console
+### Logger
+Used to log to a client in-game console

-##### info
+#### info
 Informational logs. Colored in white
 ```ts
 fw.system.log.info('some information to be logged')
 ```

-##### warn
+#### warn
 Warning logs. Colored in yellow
 ```ts
-fw.system.log.info('warning message')
+fw.system.log.warn('warning message')
 ```

-##### error
+#### error
 Error logs. Colored in red
 ```ts
-fw.system.log.info('error message')
+fw.system.log.info('some error information')
 ```

-## Client 
+## Rpc
+``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
+
+# Client 
 Package used on a client-side of your Rage:MP Server

-### Usage
+## Usage
 ```ts
 import { fw } from '@entityseven/rage-fw-client'
 ```
 Only usable in client environment. For usage in [Server](#server) and [Browser](#browser) refer to their docs

-### Declaration
+## Declaration
 ```ts
 fw = {
    event: Client,
@ -135,86 +162,114 @@ fw = {
 ```
 Further documentation will describe the fields included in ``fw``

-### Client
-Handles event manipulations that do not require player to be present in context
+## Client
+Client-side interactions

-#### register
-Registers client event
+### register
+Registers a client event with an associated callback
 ```ts
-fw.event.register('clientEventName', ([arg1, arg2]) => {
-    // your logic here
+fw.event.register("playerDeath", (player, reason, killer) => {
+    // do something
+})
+
+// Registering an event with middlewares
+fw.event.register("playerDeath", (player, reason, killer) => {
+    // do something
+}, {
+    middlewares: [...] // <- your middlewares here
+})
+
+// or
+
+fw.event.register("playerDeath", (player, reason, killer) => {
+    // do something
+}, {
+    middlewares: {
+        executables: [...], // <- your middlewares here
+        onError: (msg) => void msg // <- error handling here
+    }
 })
 ```

-#### unregister
-Unregisters client event
+### unregister
+Unregisters a client event, removing the associated callback
 ```ts
-fw.event.unregister('clientEventName')
+fw.event.unregister("playerDeath")
 ```

-### Player
+## Player
 Handles event manipulations that require player to be present in context

-#### trigger
+### browser
+Setter. Also shares browser with ``rage-fw-rpc``
+```ts
+fw.player.browser = mp.browsers.new('package://index.html')
+```
+
+### trigger
 Triggers registered client event with passed arguments. Formerly known as ``call`` or ``emit``
 ```ts
-fw.player.trigger('clientEventName', ['arg1', 2])
+// without args
+fw.player.trigger("clientEventName")
+// with args
+fw.player.trigger("clientEventName", ["message to me"])
 ```

-#### triggerServer
-Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer``
+### triggerServer
+Triggers a server event from the client with arguments from shared types. Formerly known as ``callServer`` or ``emitServer``
 ```ts
-fw.player.triggerServer('serverEventName', ['arg1', 2])
+// without args
+fw.player.triggerServer("serverEventName")
+// with args
+fw.player.triggerServer("serverEventName", ["message to server"])
 ```

-#### triggerBrowser
-Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser``
+### triggerBrowser
+Triggers a browser event from the client with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser``
 ```ts
-fw.player.triggerBrowser('cefEventName', ['arg1', 2])
+// without args
+fw.player.triggerBrowser("browserEventName")
+// with args
+fw.player.triggerBrowser("browserEventName", ["message to browser"])
 ```

-### Browser 
+## System
+Handles functions used to interact with the client environment

-#### registerBrowser
-Used to assign a browser instance. Returns the same browser instance
-```ts
-fw.browser.registerBrowser(browserInstance)
-```
+### Logger
+Used to log to a client in-game console

-### System
-Handles functions used to interact with system environment
-
-#### Logger
-Used to log in a client in-game console
-
-##### info
+#### info
 Informational logs. Colored in white
 ```ts
 fw.system.log.info('some information to be logged')
 ```

-##### warn
+#### warn
 Warning logs. Colored in yellow
 ```ts
-fw.system.log.info('warning message')
+fw.system.log.warn('warning message')
 ```

-##### error
+#### error
 Error logs. Colored in red
 ```ts
-fw.system.log.info('error message')
+fw.system.log.info('some error information')
 ```

-## Browser
+## Rpc
+``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
+
+# Browser
 Package used on a browser-side of your Rage:MP Server

-### Usage
+## Usage
 ```ts
 import { fw } from '@entityseven/rage-fw-browser'
 ```
-Only usable in CEF environment. For usage in [Server](#server) and [Client](#client) refer to their docs
+Only usable in Browser environment. For usage in [Server](#server) and [Client](#client) refer to their docs

-### Declaration
+## Declaration
 ```ts
 fw = {
    event: Browser,
@ -223,34 +278,128 @@ fw = {
 ```
 Further documentation will describe the fields included in ``fw``

-### Cef
+## Browser
+Browser-side interactions

-#### register
-Registers CEF event
+### register
+Registers a browser event with an associated callback
 ```ts
-fw.event.register('cefEventName', ([arg1, arg2]) => {
-    // your logic here
+fw.event.register("showNotification", (message, color) => {
+    // do something
 })
 ```

-#### trigger
-Triggers registered CEF event with passed arguments. Formerly known as ``call`` or ``emit``
+
+### unregister
+Unregisters a browser event, removing the associated callback
 ```ts
-fw.event.trigger('clientEventName', ['arg1', 2])
+fw.event.unregister("showNotification")
 ```

-#### triggerServer
-Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer``
+### trigger
+Triggers a browser event from the browser with arguments from shared types. Formerly known as ``call`` or ``emit``
 ```ts
-fw.event.triggerServer('serverEventName', ['arg1', 2])
+// without args
+fw.event.trigger("browserEventName")
+// with args
+fw.event.trigger("browserEventName", ["message to me"])
 ```

-#### triggerClient
-Triggers registered client event with passed arguments. Formerly known as ``trigger``
+### triggerServer
+Triggers a server event from the browser with arguments from shared types. Formerly known as ``callServer`` or ``emitServer``
 ```ts
-fw.event.triggerClient('clientEventName', ['arg1', 2])
+// without args
+fw.event.triggerServer("serverEventName")
+// with args
+fw.event.triggerServer("serverEventName", ["message to server"])
 ```

-## Features
-### Event Middlewares
-todo
+### triggerClient
+Triggers a client event from the browser with arguments from shared types. Formerly known as ``callClient`` or ``emitClient``
+```ts
+// without args
+fw.event.triggerClient("clientEventName")
+// with args
+fw.event.triggerClient("clientEventName", ["message to client"])
+```
+
+## Rpc
+``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
+
+# Features
+## Event Middlewares
+Rage FW offers you to add middlewares when registering events in Client and Server environments, to check if callback should be executed or should not. Core class functionality is not exposed to user, but some types are for easier code managing. Here are some key points (in context of Server environment, but also applicable to Client)
+
+### Declaration
+```ts
+register(
+    eventName,
+    callback,
+    options?: {
+        middlewares?: RageFW_MiddlewareOptions
+    },
+)
+
+type RageFW_MiddlewareOptions = 
+    | RageFW_MiddlewareFunction[]
+    | {
+          executables: RageFW_MiddlewareFunction[]
+          onError: (error: string) => unknown
+      }
+
+type RageFW_MiddlewareFunction = (...args: T.RageFW_ServerArgs) => 
+    Promise<RageFW_MiddlewareResponse>
+
+type RageFW_MiddlewareResponse =
+    | {
+          success: boolean
+          message?: string
+      }
+    | boolean
+```
+
+### Usage
+``RageFW_MiddlewareFunction`` can be imported to type your middlewares, eg.:
+```ts
+import {type RageFW_MiddlewareFunction} from '@entityseven/rage-fw-server'
+
+const isPlayerAdmin: RageFW_MiddlewareFunction<'yourEventName'> = async (player, ...args) => {
+    if (player.adminLvl >= 2) {
+    	return true
+    } else {
+    	return {
+			success: false,
+            message: 'You must have administrator rights for this action'
+        }
+    }
+}
+
+// or function-like if you want to omit some argument types or hoisting is required
+
+async function isPlayerAdmin(player: PlayerMp, ...args): ReturnType<RageFW_MiddlewareFunction<'yourEventName'>> {
+    if (player.adminLvl >= 2) {
+        return true
+    } else {
+        return {
+            success: false,
+            message: 'You must have administrator rights for this action',
+        }
+    }
+}
+
+fw.event.register(
+    'yourEventName',
+    async (player, ...args) => {
+        // do an action which requires administrator rights
+    },
+    {
+        middlewares: {
+            executables: [isPlayerAdmin],
+            onError: e => {}, // notify player about missing permissions
+        },
+    },
+)
+``` 
+
+### Implementation TL;DR (why no next()?)
+Unfortunately in Client-side of Rage:MP every thrown ``Error`` or ``Promise.reject`` is not ``catch``able, meaning a naughty error window will pop-up on player's screen. Due to this implementation variant we were forced to not throw ``Errors`` from middlewares and just return middleware result. Server-side can handle errors, but to keep everything consistent we stick up to this variant