init

RPC-%40-0.2.1.md

@@ -0,0 +1,141 @@
+# Rage-FW-RPC
+is an all-in package with asynchronous RPC implementation for RageMP servers in JS/TS
+
+# Installation
+``` shell 
+npm i rage-fw-rpc
+```
+```shell 
+pnpm i rage-fw-rpc
+```
+```shell 
+yarn add rage-fw-rpc
+```
+
+Import installed package and initialize rpc:
+```ts
+// lib/rpc.js
+
+import { Rpc } from 'rage-fw-rpc'
+export const rpc = new Rpc(/* options */)
+```
+On client-side you have to also specify the browser you want to refer to for events
+```ts
+// client/index.js
+
+import { Rpc } from 'rage-fw-rpc'
+export const rpc = new Rpc(/* options */)
+rpc.browser = mp.browsers.new('package://.../index.html')
+```
+
+# Motivation
+The idea was to create an extensible package, with various features to simplify the development process and provide as much comfort as possible. It should also be using similar architecture as the framework it was specially built for
+
+Inspired by usage of [rage-rpc](https://github.com/micaww/rage-rpc)
+
+
+# TL;DR
+- Type-safe events via [TS generics](https://www.typescriptlang.org/docs/handbook/2/generics.html), avoiding type wrappers
+- Built-in logging options for each environment 
+- Error-safe developer mode for browser
+- Calls can receive response from called environments via Promises (browser -> server -> browser, etc.)
+- Actual human-readable errors
+
+# Points
+Before reading docs you should at least barely be acknowledged about the patterns used and how ``rage-fw-rpc`` is different in usage than community favorite ``rage-rpc`` 
+
+**todo**
+
+# Docs
+
+## Rpc Config
+These are the options you can specify when creating Rpc instance. Options can be omitted at all if you want so. All options only have effect in current context and have to be specified individually on server/client/browser
+```ts
+interface RpcWrapperConfig {
+    forceBrowserDevMode?: boolean // defaults to false
+    debugLogs?: boolean // defaults to false
+}
+```
+``forceBrowserDevMode`` - only has effect on browser-side. Fallback for browser to launch without mp context and without errors (eg. for development in browser). Keep in mind that using this makes browser-side unavailable at all preventing from all operations except logging. Therefore is recommended to use in pair with ``debugLogs``
+
+``debugLogs`` -  enables logging all exposed methods to available console. Server/browser: ``console.log``; client: ``mp.console.logInfo``
+```ts
+// example
+
+import { Rpc } from 'rage-fw-rpc'
+export const rpc = new Rpc({
+    forceBrowserDevMode: false
+    debugLogs: true
+})
+```
+
+## register
+Registers a callback function for a specified event 
+
+**todo** describe generics
+```ts
+rpc.register('playerJoin', (player) => {
+  console.log(`Connected: ${player.socialClub}`)
+})
+```
+
+## unregister
+Unregisters callback function for a specified event
+```ts
+rpc.unregister('playerDamage')
+```
+
+## callClient
+Calls a client-side event from server or browser
+
+From browser:
+```ts
+rpc.callClient('updatePlayerData', ['argument']).then(response => {
+    console.log(`Received: ${response}`)
+})
+```
+From server (requires player):
+```ts
+rpc.callClient(player, 'updatePlayerData', ['argument']).then(response => {
+    console.log(`Received: ${response}`)
+})
+```
+
+## callServer
+Calls a server-side event from browser or client
+```ts
+rpc.callServer('updatePlayerData', ['argument']).then(response => {
+  console.log(`Received: ${response}`)
+})
+```
+
+## callBrowser
+Calls a server-side event from browser or client
+
+From client:
+```ts
+rpc.callBrowser('updatePlayerData', ['argument']).then(response => {
+    console.log(`Received: ${response}`)
+})
+```
+From client (requires player):
+```ts
+rpc.callBrowser(player, 'updatePlayerData', ['argument']).then(response => {
+    console.log(`Received: ${response}`)
+})
+```
+
+## call
+Calls an event in current environment
+```ts
+rpc.call('triggerSomething').then(response => {
+    console.log(`Received: ${response}`)
+})
+```
+
+# Errors
+These should be clear enough themselves, in other cases refer to here
+- ``EVENT_NOT_REGISTERED`` - throws in Promise (rejects) in called environment when event is either already unregistered or not registered yet. If you see this its almost always calling an event before registering
+- ``UNKNOWN_ENVIRONMENT`` - throws in any environment that is not recognized as server/client/browser in Rage. Unlike ``rage-rpc`` this is not thrown in browser when launched without mp context IF you specify it in browser rpc options (see Options)
+- ``NO_BROWSER`` - throws on client if you failed to specify valid browser for it to refer to when calling browser
+- ``EVENT_RESPONSE_TIMEOUT`` - throws in Promise (rejects) when failed to receive a response data from called environment. You may not always want to receive it at all, for now it just works like this. Prefer adding ``catch`` on your events