From 12d2197e18a15e3a9a74c265b71c9c902f367425 Mon Sep 17 00:00:00 2001 From: Danya H Date: Fri, 31 Jan 2025 21:40:16 +0000 Subject: [PATCH] upd (fw/rpc): - (rpc) removed unnecessary return type generics - (fw) implemented synchronous versions of rpc events to omit waiting for response - (fw) more descriptive docs --- browser/src/core/browser.ts | 112 +++++++++++++++++++++++++++++++----- client/src/core/player.ts | 109 ++++++++++++++++++++++++++++++----- rpc/src/index.ts | 5 -- server/src/core/player.ts | 82 +++++++++++++++++++++++--- 4 files changed, 270 insertions(+), 38 deletions(-) diff --git a/browser/src/core/browser.ts b/browser/src/core/browser.ts index 67b40c9..ddd43c2 100644 --- a/browser/src/core/browser.ts +++ b/browser/src/core/browser.ts @@ -75,12 +75,42 @@ export class FW_Browser extends FW_Helper { } /** - * Triggers a browser event from the browser with arguments from shared types + * Triggers a browser event from the browser with arguments from 'rage-fw-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 {void} + * + * @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 trigger( + eventName: EventName, + ...args: T._BrowserEventHasArgs extends true + ? [T.FW_BrowserArgs] + : [] + ): void { + this.log_('[RPC](trigger):', eventName, ...args) + + rpc.call(eventName, args) + } + + /** + * Triggers an asynchronous browser event from the browser with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callAsync`` or ``emitAsync`` + * + * @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 @@ -93,7 +123,7 @@ export class FW_Browser extends FW_Helper { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async trigger( + public async triggerAsync( eventName: EventName, ...args: T._BrowserEventHasArgs extends true ? [T.FW_BrowserArgs] @@ -101,7 +131,7 @@ export class FW_Browser extends FW_Helper { ): Promise> { this.log_('[RPC](trigger):', eventName, ...args) - return await rpc.call< + return await rpc.callAsync< typeof args, EventName, T.FW_BrowserReturn @@ -109,12 +139,42 @@ export class FW_Browser extends FW_Helper { } /** - * Triggers a server event from the browser with arguments from shared types + * Triggers a server event from the browser with arguments from 'rage-fw-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 {void} + * + * @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 triggerServer( + eventName: EventName, + ...args: T._ServerEventHasArgs extends true + ? [T.FW_ServerArgs] + : [] + ): void { + this.log_('[RPC](triggerServer):', eventName, ...args) + + rpc.callServer(eventName, args) + } + + /** + * Triggers an asynchronous server event from the browser with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callServerAsync`` or ``emitServerAsync`` + * + * @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 @@ -127,7 +187,7 @@ export class FW_Browser extends FW_Helper { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerServer( + public async triggerServerAsync( eventName: EventName, ...args: T._ServerEventHasArgs extends true ? [T.FW_ServerArgs] @@ -135,7 +195,7 @@ export class FW_Browser extends FW_Helper { ): Promise> { this.log_('[RPC](triggerServer):', eventName, ...args) - return await rpc.callServer< + return await rpc.callServerAsync< typeof args, EventName, T.FW_ServerReturn @@ -143,12 +203,42 @@ export class FW_Browser extends FW_Helper { } /** - * Triggers a client event from the browser with arguments from shared types + * Triggers a browser event from the browser with arguments from 'rage-fw-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 {void} + * + * @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 triggerClient( + eventName: EventName, + ...args: T._ClientEventHasArgs extends true + ? [T.FW_ClientArgs] + : [] + ): void { + this.log_('[RPC](triggerClient):', eventName, ...args) + + rpc.callClient(eventName, args) + } + + /** + * Triggers an asynchronous client event from the browser with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callClientAsync`` or ``emitClientAsync`` + * + * @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 @@ -161,7 +251,7 @@ export class FW_Browser extends FW_Helper { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerClient( + public async triggerClientAsync( eventName: EventName, ...args: T._ClientEventHasArgs extends true ? [T.FW_ClientArgs] @@ -169,14 +259,10 @@ export class FW_Browser extends FW_Helper { ): Promise> { this.log_('[RPC](triggerClient):', eventName, ...args) - return await rpc.callClient< + return await rpc.callClientAsync< typeof args, EventName, T.FW_ClientReturn >(eventName, args) } } - -// new Browser() -// .register('customCefEvent', async (a, b) => true) -// .triggerServer('customServerEvent', ['', 1]) diff --git a/client/src/core/player.ts b/client/src/core/player.ts index 4fb73d9..73fee36 100644 --- a/client/src/core/player.ts +++ b/client/src/core/player.ts @@ -14,12 +14,40 @@ export class FW_Player { } /** - * Triggers a client event from the client with arguments from shared types + * Triggers a client event from the client with arguments from 'rage-fw-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 {void} + * + * @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 trigger( + eventName: EventName, + ...args: T._ClientEventHasArgs extends true + ? [T.FW_ClientArgs] + : [] + ): void { + rpc.call(eventName, args) + } + + /** + * Triggers an asynchronous client event from the client with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callAsync`` or ``emitAsync`` + * + * @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 @@ -32,13 +60,13 @@ export class FW_Player { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async trigger( + public async triggerAsync( eventName: EventName, ...args: T._ClientEventHasArgs extends true ? [T.FW_ClientArgs] : [] ): Promise> { - return await rpc.call< + return await rpc.callAsync< typeof args, EventName, T.FW_ClientReturn @@ -46,12 +74,40 @@ export class FW_Player { } /** - * Triggers a server event from the client with arguments from shared types + * Triggers a server event from the client with arguments from 'rage-fw-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 {void} + * + * @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 triggerServer( + eventName: EventName, + ...args: T._ServerEventHasArgs extends true + ? [T.FW_ServerArgs] + : [] + ): void { + rpc.callServer(eventName, args) + } + + /** + * Triggers an asynchronous server event from the client with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callServerAsync`` or ``emitServerAsync`` + * + * @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 @@ -64,13 +120,13 @@ export class FW_Player { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerServer( + public async triggerServerAsync( eventName: EventName, ...args: T._ServerEventHasArgs extends true ? [T.FW_ServerArgs] : [] ): Promise> { - return await rpc.callServer< + return await rpc.callServerAsync< typeof args, EventName, T.FW_ClientServerReturn @@ -78,12 +134,43 @@ export class FW_Player { } /** - * Triggers a browser event from the client with arguments from shared types + * Triggers a browser event from the client with arguments from 'rage-fw-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 {void} + * + * @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 triggerBrowser( + eventName: EventName, + ...args: T._BrowserEventHasArgs extends true + ? [T.FW_BrowserArgs] + : [] + ): void { + if (!this._browser) + throw new Error('You need to initialize browser first') + + rpc.callBrowser(eventName, args) + } + + /** + * Triggers an asynchronous browser event from the client with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callBrowserAsync`` or ``emitBrowserAsync`` + * + * @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 @@ -96,7 +183,7 @@ export class FW_Player { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerBrowser( + public async triggerBrowserAsync( eventName: EventName, ...args: T._BrowserEventHasArgs extends true ? [T.FW_BrowserArgs] @@ -105,14 +192,10 @@ export class FW_Player { if (!this._browser) throw new Error('You need to initialize browser first') - return await rpc.callBrowser< + return await rpc.callBrowserAsync< typeof args, EventName, T.FW_BrowserReturn >(eventName, args) } } - -// new Player().trigger('customClientEvent', ['', 1]) -// new Player().triggerServer('customServerEvent', ['', 1]) -// new Player().triggerBrowser('customCefEvent', ['', 1]) diff --git a/rpc/src/index.ts b/rpc/src/index.ts index d9fc457..3eef9f7 100644 --- a/rpc/src/index.ts +++ b/rpc/src/index.ts @@ -153,7 +153,6 @@ class Rpc extends Wrapper { public callClient< Arguments extends unknown[] = unknown[], EventName extends string = string, - Return = unknown, >(eventName: EventName, args?: Arguments): void /** * Calls a client-side event from server or server. Use 'call' to call client from client @@ -173,7 +172,6 @@ class Rpc extends Wrapper { public callClient< Arguments extends unknown[] = unknown[], EventName extends string = string, - Return = unknown, >(player: PlayerMp, eventName: EventName, args?: Arguments): void public callClient( playerOrEventName: PlayerMp | string, @@ -519,7 +517,6 @@ class Rpc extends Wrapper { public callBrowser< Arguments extends unknown[] = unknown[], EventName extends string = string, - Return = unknown, >(eventName: EventName, args?: Arguments): void /** * Calls a browser-side event from client or server. Use 'call' to call browser from browser @@ -539,7 +536,6 @@ class Rpc extends Wrapper { public callBrowser< Arguments extends unknown[] = unknown[], EventName extends string = string, - Return = unknown, >(player: PlayerMp, eventName: EventName, args?: Arguments): void public callBrowser( playerOrEventName: PlayerMp | string, @@ -741,7 +737,6 @@ class Rpc extends Wrapper { public call< Arguments extends unknown[] = unknown[], EventName extends string = string, - Return = unknown, >(eventName: EventName, args?: Arguments): void { this.log('call', eventName, args) if (this.forceBrowserDevMode_) return diff --git a/server/src/core/player.ts b/server/src/core/player.ts index 963c872..9ab79b9 100644 --- a/server/src/core/player.ts +++ b/server/src/core/player.ts @@ -4,13 +4,43 @@ import type * as T from '../types' /** Handles event manipulations that require player to be present in context */ export class FW_Player { /** - * Triggers a client event from the server with arguments from shared types + * Triggers a client event from the server with arguments from 'rage-fw-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 {void} + * + * @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 triggerClient( + player: PlayerMp, + eventName: EventName, + ...args: T._ClientEventHasArgs extends true + ? [T.FW_ClientArgs] + : [] + ): void { + rpc.callClient(player, eventName, args) + } + + /** + * Triggers an asynchronous client event from the server with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callClientAsync`` or ``emitClientAsync`` + * + * @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 @@ -23,25 +53,29 @@ export class FW_Player { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerClient( + public async triggerClientAsync( player: PlayerMp, eventName: EventName, ...args: T._ClientEventHasArgs extends true ? [T.FW_ClientArgs] : [] ): Promise> { - return await rpc.callClient(player, eventName, args) + return await rpc.callClientAsync< + typeof args, + EventName, + T.FW_ClientReturn + >(player, eventName, args) } /** - * Triggers a browser event from the server with arguments from shared types + * Triggers a browser event from the server with arguments from 'rage-fw-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 + * @returns {void} * * @example * // Triggering a browser event without arguments @@ -53,13 +87,47 @@ export class FW_Player { * * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} */ - public async triggerBrowser( + public triggerBrowser( + player: PlayerMp, + eventName: EventName, + ...args: T._BrowserEventHasArgs extends true + ? [T.FW_BrowserArgs] + : [] + ): void { + rpc.callBrowser(player, eventName, args) + } + + /** + * Triggers an asynchronous browser event from the server with arguments from 'rage-fw-shared-types', and expects to receive a response from an event + * + * Formerly known as ``callBrowserAsync`` or ``emitBrowserAsync`` + * + * @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.triggerBrowserAsync("browserEventName") + * + * @example + * // Triggering a browser event with arguments + * fw.player.triggerBrowserAsync("browserEventName", ["message to browser"]) + * + * @see {@link https://git.entityseven.com/entityseven/rage-framework/wiki Wiki} + */ + public async triggerBrowserAsync( player: PlayerMp, eventName: EventName, ...args: T._BrowserEventHasArgs extends true ? [T.FW_BrowserArgs] : [] ): Promise> { - return await rpc.callBrowser(player, eventName, args) + return await rpc.callBrowserAsync< + typeof args, + EventName, + T.FW_BrowserReturn + >(player, eventName, args) } }