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
This commit is contained in:
Danya H 2025-01-31 21:40:16 +00:00
parent 897fd5a9f5
commit 12d2197e18
4 changed files with 270 additions and 38 deletions

View File

@ -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 extends T.FW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
: []
): void {
this.log_('[RPC](trigger):', eventName, ...args)
rpc.call<typeof args, EventName>(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<EventName extends T.FW_BrowserEvent>(
public async triggerAsync<EventName extends T.FW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
@ -101,7 +131,7 @@ export class FW_Browser extends FW_Helper {
): Promise<T.FW_BrowserReturn<EventName>> {
this.log_('[RPC](trigger):', eventName, ...args)
return await rpc.call<
return await rpc.callAsync<
typeof args,
EventName,
T.FW_BrowserReturn<EventName>
@ -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 extends T.FW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> extends true
? [T.FW_ServerArgs<EventName>]
: []
): void {
this.log_('[RPC](triggerServer):', eventName, ...args)
rpc.callServer<typeof args, EventName>(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<EventName extends T.FW_ServerEvent>(
public async triggerServerAsync<EventName extends T.FW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> extends true
? [T.FW_ServerArgs<EventName>]
@ -135,7 +195,7 @@ export class FW_Browser extends FW_Helper {
): Promise<T.FW_ServerReturn<EventName>> {
this.log_('[RPC](triggerServer):', eventName, ...args)
return await rpc.callServer<
return await rpc.callServerAsync<
typeof args,
EventName,
T.FW_ServerReturn<EventName>
@ -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 extends T.FW_ClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
: []
): void {
this.log_('[RPC](triggerClient):', eventName, ...args)
rpc.callClient<typeof args, EventName>(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<EventName extends T.FW_ClientEvent>(
public async triggerClientAsync<EventName extends T.FW_ClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
@ -169,14 +259,10 @@ export class FW_Browser extends FW_Helper {
): Promise<T.FW_ClientReturn<EventName>> {
this.log_('[RPC](triggerClient):', eventName, ...args)
return await rpc.callClient<
return await rpc.callClientAsync<
typeof args,
EventName,
T.FW_ClientReturn<EventName>
>(eventName, args)
}
}
// new Browser()
// .register('customCefEvent', async (a, b) => true)
// .triggerServer('customServerEvent', ['', 1])

View File

@ -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 extends keyof T.FW_ICustomClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
: []
): void {
rpc.call<typeof args, EventName>(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<EventName extends keyof T.FW_ICustomClientEvent>(
public async triggerAsync<EventName extends keyof T.FW_ICustomClientEvent>(
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
: []
): Promise<T.FW_ClientReturn<EventName>> {
return await rpc.call<
return await rpc.callAsync<
typeof args,
EventName,
T.FW_ClientReturn<EventName>
@ -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 extends T.FW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> extends true
? [T.FW_ServerArgs<EventName>]
: []
): void {
rpc.callServer<typeof args, EventName>(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<EventName extends T.FW_ServerEvent>(
public async triggerServerAsync<EventName extends T.FW_ServerEvent>(
eventName: EventName,
...args: T._ServerEventHasArgs<EventName> extends true
? [T.FW_ServerArgs<EventName>]
: []
): Promise<T.FW_ClientServerReturn<EventName>> {
return await rpc.callServer<
return await rpc.callServerAsync<
typeof args,
EventName,
T.FW_ClientServerReturn<EventName>
@ -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 extends T.FW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
: []
): void {
if (!this._browser)
throw new Error('You need to initialize browser first')
rpc.callBrowser<typeof args, EventName>(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<EventName extends T.FW_BrowserEvent>(
public async triggerBrowserAsync<EventName extends T.FW_BrowserEvent>(
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
@ -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>
>(eventName, args)
}
}
// new Player().trigger('customClientEvent', ['', 1])
// new Player().triggerServer('customServerEvent', ['', 1])
// new Player().triggerBrowser('customCefEvent', ['', 1])

View File

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

View File

@ -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<EventName extends T.FW_ClientEvent>(
player: PlayerMp,
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
: []
): void {
rpc.callClient<typeof args, EventName>(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<EventName extends T.FW_ClientEvent>(
public async triggerClientAsync<EventName extends T.FW_ClientEvent>(
player: PlayerMp,
eventName: EventName,
...args: T._ClientEventHasArgs<EventName> extends true
? [T.FW_ClientArgs<EventName>]
: []
): Promise<T.FW_ClientReturn<EventName>> {
return await rpc.callClient(player, eventName, args)
return await rpc.callClientAsync<
typeof args,
EventName,
T.FW_ClientReturn<EventName>
>(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<EventName extends T.FW_BrowserEvent>(
public triggerBrowser<EventName extends T.FW_BrowserEvent>(
player: PlayerMp,
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
: []
): void {
rpc.callBrowser<typeof args, EventName>(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<EventName extends T.FW_BrowserEvent>(
player: PlayerMp,
eventName: EventName,
...args: T._BrowserEventHasArgs<EventName> extends true
? [T.FW_BrowserArgs<EventName>]
: []
): Promise<T.FW_BrowserReturn<EventName>> {
return await rpc.callBrowser(player, eventName, args)
return await rpc.callBrowserAsync<
typeof args,
EventName,
T.FW_BrowserReturn<EventName>
>(player, eventName, args)
}
}