fivem-rpc 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# fivem-rpc
+
+![NPM Version](https://img.shields.io/npm/v/fivem-rpc)
+
+Typed RPC for FiveM. Replaces raw `emitNet`/`onNet` calls with typed, Promise-based procedures between server, client and NUI.
+
+## Installation
+
+```sh
+pnpm add fivem-rpc
+```
+
+## Setup
+
+Declare your procedures once by augmenting the registry interfaces from `fivem-rpc/types`. Both sides import the same declarations.
+
+```ts
+import type { RpcPayload } from "fivem-rpc/types";
+
+declare module "fivem-rpc/types" {
+  interface ClientToServerRpc {
+    "foo:getData": RpcPayload<{ id: number }, { name: string }>;
+    "foo:ping":    RpcPayload<undefined, undefined>;
+  }
+
+  interface ServerToClientRpc {
+    "bar:notify": RpcPayload<{ message: string }, { seen: boolean }>;
+  }
+
+  interface NuiToClientRpc {
+    "ui:getInfo": RpcPayload<undefined, { name: string }>;
+  }
+
+  interface ClientToNuiRpc {
+    "ui:show": RpcPayload<{ text: string }, { ok: boolean }>;
+  }
+}
+```
+
+`RpcPayload<Request, Response>` describes the argument and return value of a procedure. Use `undefined` for no argument or no return value.
+
+## Client to Server
+
+On the server, register a handler:
+
+```ts
+import { initializeRpc } from "fivem-rpc/server";
+
+const { onClientRpc } = initializeRpc();
+
+onClientRpc("foo:getData", async (source, { id }) => {
+  return { name: "bar" };
+});
+```
+
+On the client, call the procedure:
+
+```ts
+import { initializeRpc } from "fivem-rpc/client";
+
+const { callServerRpc } = initializeRpc();
+
+const result = await callServerRpc("foo:getData", { id: 1 });
+if (result.success) {
+  console.log(result.data.name);
+}
+```
+
+## Server to Client
+
+On the client, register a handler:
+
+```ts
+const { onServerRpc } = initializeRpc();
+
+onServerRpc("bar:notify", async ({ message }) => {
+  console.log(message);
+  return { seen: true };
+});
+```
+
+On the server, call the procedure:
+
+```ts
+const { callClientRpc } = initializeRpc();
+
+const result = await callClientRpc(playerId, "bar:notify", { message: "hello" });
+if (result.success) {
+  console.log(result.data.seen);
+}
+```
+
+## NUI ↔ Client
+
+### NUI to Client
+
+On the client, register a handler:
+
+```ts
+// client script
+const { onNuiRpc } = initializeRpc();
+
+onNuiRpc("ui:getInfo", async () => {
+  return { name: GetPlayerName("-1") };
+});
+```
+
+In NUI, call the procedure:
+
+```ts
+// browser (fivem-rpc/nui)
+import { initializeRpc } from "fivem-rpc/nui";
+
+const { callClientRpc } = initializeRpc();
+
+const result = await callClientRpc("ui:getInfo");
+if (result.success) {
+  document.title = result.data.name;
+}
+```
+
+### Client to NUI
+
+In NUI, register a handler:
+
+```ts
+// browser (fivem-rpc/nui)
+const { onClientRpc } = initializeRpc();
+
+onClientRpc("ui:show", async ({ text }) => {
+  showNotification(text);
+  return { ok: true };
+});
+```
+
+On the client, call the procedure:
+
+```ts
+// client script
+const { callNuiRpc } = initializeRpc();
+
+const result = await callNuiRpc("ui:show", { text: "hello" });
+if (result.success) {
+  console.log(result.data.ok);
+}
+```
+
+## Removing handlers
+
+All `onXxxRpc` functions have a corresponding `offXxxRpc`. Call it with just the procedure name to unconditionally remove the handler, or pass the original handler reference to only remove it if it is still the currently registered one.
+
+```ts
+const handler = async () => ({ name: "bar" });
+
+onClientRpc("foo:getData", handler);
+
+// Remove unconditionally:
+offClientRpc("foo:getData");
+
+// Remove only if this is still the registered handler:
+offClientRpc("foo:getData", handler);
+```
+
+| Entry point | Register | Unregister |
+| --- | --- | --- |
+| `fivem-rpc/server` | `onClientRpc` | `offClientRpc` |
+| `fivem-rpc/client` | `onServerRpc`, `onNuiRpc` | `offServerRpc`, `offNuiRpc` |
+| `fivem-rpc/nui` | `onClientRpc` | `offClientRpc` |
+
+## Error handling
+
+All call functions always resolve. Check `result.success` before accessing `result.data`.
+
+On failure, `result.error` is a discriminated union:
+
+```ts
+const result = await callServerRpc("foo:getData", { id: 1 });
+
+if (!result.success) {
+  switch (result.error.code) {
+    case "ERR_NO_HANDLER":
+      console.error("no handler for", result.error.procedure);
+      break;
+    case "ERR_TIMEOUT":
+      console.error("timed out waiting for", result.error.procedure);
+      break;
+    case "ERR_HANDLER":
+      console.error("handler threw:", result.error.message);
+      break;
+  }
+}
+```
+
+| Code | Cause |
+| --- | --- |
+| `ERR_NO_HANDLER` | No handler registered for the procedure |
+| `ERR_TIMEOUT` | Response not received within the timeout |
+| `ERR_HANDLER` | Handler threw at runtime |
+
+## Channels
+
+`initializeRpc` accepts an optional `channel` name (defaults to `"default"`). A channel scopes all internal event names so that two independent systems in the same resource cannot interfere with each other.
+
+Use multiple channels when you want to initialise RPC more than once in the same resource, for example to keep unrelated feature sets isolated:
+
+```ts
+const core = initializeRpc({ channel: "core" });
+const player = initializeRpc({ channel: "player" });
+```
+
+The channel name must match on both the server and client side. If you only call `initializeRpc` once per resource, you can omit it entirely and rely on the default.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `channel` | `"default"` | Scopes all event names to this channel |
+| `timeout` | `10000` | Milliseconds to wait for a response before resolving with `ERR_TIMEOUT` |

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import type { ClientToServerRpc, ServerToClientRpc, NuiToClientRpc, ClientToNuiRpc, RpcPayload, RpcResult } from "./types.js";
+type InitializeRpcOptions = {
+    /**
+     * Channel name used to scope RPC events.
+     * Must match the `channel` passed to `initializeRpc` on the server.
+     * @default "default"
+     */
+    channel?: string;
+    /**
+     * Timeout for RPC responses in milliseconds.
+     * @default 10000
+     */
+    timeout?: number;
+};
+/**
+ * Initializes a client-side RPC channel.
+ *
+ * Each channel is isolated. Calling with the same channel name twice throws.
+ *
+ * @example
+ * const { callServerRpc } = initializeRpc({ channel: "core" });
+ * const result = await callServerRpc("core:ping");
+ */
+export declare const initializeRpc: ({ channel, timeout, }?: InitializeRpcOptions) => {
+    /**
+     * Calls a server-side RPC procedure. Always resolves; inspect `result.success` to branch.
+     *
+     * @example
+     * const result = await callServerRpc("player:getData");
+     * if (result.success) console.log(result.data.name);
+     * else console.error(result.error.message);
+     */
+    callServerRpc: <Key extends keyof ClientToServerRpc>(procedure: Key, ...args: ClientToServerRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<RpcResult<ClientToServerRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>>;
+    /** Registers a handler for a server-to-client RPC procedure. */
+    onServerRpc: <Key extends keyof ServerToClientRpc>(procedure: Key, handler: (...args: ServerToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ServerToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /** Removes a handler for a server-to-client RPC procedure. */
+    offServerRpc: <Key extends keyof ServerToClientRpc>(procedure: Key, handler?: (...args: ServerToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ServerToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /**
+     * Calls a NUI procedure and returns a typed Promise.
+     * The NUI must have a corresponding `onClientRpc` handler registered.
+     * Always resolves; inspect `result.success` to branch.
+     */
+    callNuiRpc: <Key extends keyof ClientToNuiRpc>(procedure: Key, ...args: ClientToNuiRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<RpcResult<ClientToNuiRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>>;
+    /** Registers a handler for a NUI-to-client RPC procedure. */
+    onNuiRpc: <Key extends keyof NuiToClientRpc>(procedure: Key, handler: (...args: NuiToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<NuiToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /** Removes a handler for a NUI-to-client RPC procedure. */
+    offNuiRpc: <Key extends keyof NuiToClientRpc>(procedure: Key, handler?: (...args: NuiToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<NuiToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+};
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,189 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils.ts
+/** Generates a unique call ID scoped to a procedure and channel. */
+const generateCallId = ({ procedure, channel }) => `${channel}:${procedure}:${"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+	const r = Math.random() * 16 | 0;
+	return (c === "x" ? r : r & 3 | 8).toString(16);
+})}`;
+//#endregion
+//#region src/client.ts
+const activeChannels = /* @__PURE__ */ new Set();
+/**
+* Initializes a client-side RPC channel.
+*
+* Each channel is isolated. Calling with the same channel name twice throws.
+*
+* @example
+* const { callServerRpc } = initializeRpc({ channel: "core" });
+* const result = await callServerRpc("core:ping");
+*/
+const initializeRpc = ({ channel = "default", timeout = 1e4 } = {}) => {
+	if (activeChannels.has(channel)) throw new Error(`RPC channel already initialized: "${channel}"`);
+	activeChannels.add(channel);
+	const request = `__rpc_c2s_${channel}__`;
+	const response = `__rpc_c2s_response_${channel}__`;
+	const pendingResponses = /* @__PURE__ */ new Map();
+	const onRpcResponse = (handler) => onNet(response, handler);
+	const emitRpcRequest = (callId, procedure, args) => emitNet(request, callId, procedure, args);
+	onRpcResponse((callId, result) => {
+		const pending = pendingResponses.get(callId);
+		if (!pending) return;
+		pendingResponses.delete(callId);
+		clearTimeout(pending.timer);
+		pending.resolve(result);
+	});
+	const serverToClientHandlers = /* @__PURE__ */ new Map();
+	const nuiToClientHandlers = /* @__PURE__ */ new Map();
+	const clientToNuiPending = /* @__PURE__ */ new Map();
+	RegisterNuiCallbackType(`__rpc_nui2c_${channel}__`);
+	on(`__cfx_nui:__rpc_nui2c_${channel}__`, async (data, cb) => {
+		const handler = nuiToClientHandlers.get(data.procedure);
+		if (!handler) {
+			cb({
+				success: false,
+				error: {
+					code: "ERR_NO_HANDLER",
+					procedure: data.procedure
+				}
+			});
+			return;
+		}
+		try {
+			cb({
+				success: true,
+				data: await handler(data.args)
+			});
+		} catch (e) {
+			cb({
+				success: false,
+				error: {
+					code: "ERR_HANDLER",
+					message: e instanceof Error ? e.message : String(e)
+				}
+			});
+		}
+	});
+	RegisterNuiCallbackType(`__rpc_c2nui_response_${channel}__`);
+	on(`__cfx_nui:__rpc_c2nui_response_${channel}__`, (data, cb) => {
+		const pending = clientToNuiPending.get(data.callId);
+		if (pending) {
+			clientToNuiPending.delete(data.callId);
+			clearTimeout(pending.timer);
+			pending.resolve(data.result);
+		}
+		cb({});
+	});
+	onNet(`__rpc_s2c_${channel}__`, async (callId, procedure, args) => {
+		const handler = serverToClientHandlers.get(procedure);
+		if (!handler) {
+			emitNet(`__rpc_s2c_response_${channel}__`, callId, {
+				success: false,
+				error: {
+					code: "ERR_NO_HANDLER",
+					procedure
+				}
+			});
+			return;
+		}
+		try {
+			const data = await handler(args);
+			emitNet(`__rpc_s2c_response_${channel}__`, callId, {
+				success: true,
+				data
+			});
+		} catch (e) {
+			const message = e instanceof Error ? e.message : String(e);
+			emitNet(`__rpc_s2c_response_${channel}__`, callId, {
+				success: false,
+				error: {
+					code: "ERR_HANDLER",
+					message
+				}
+			});
+		}
+	});
+	return {
+		/**
+		* Calls a server-side RPC procedure. Always resolves; inspect `result.success` to branch.
+		*
+		* @example
+		* const result = await callServerRpc("player:getData");
+		* if (result.success) console.log(result.data.name);
+		* else console.error(result.error.message);
+		*/
+		callServerRpc: (procedure, ...args) => {
+			const callId = generateCallId({
+				procedure,
+				channel
+			});
+			return new Promise((resolve) => {
+				const timer = setTimeout(() => {
+					pendingResponses.delete(callId);
+					resolve({
+						success: false,
+						error: {
+							code: "ERR_TIMEOUT",
+							procedure
+						}
+					});
+				}, timeout);
+				pendingResponses.set(callId, {
+					resolve,
+					timer
+				});
+				emitRpcRequest(callId, procedure, args[0] ?? null);
+			});
+		},
+		/** Registers a handler for a server-to-client RPC procedure. */
+		onServerRpc: (procedure, handler) => {
+			serverToClientHandlers.set(procedure, handler);
+		},
+		/** Removes a handler for a server-to-client RPC procedure. */
+		offServerRpc: (procedure, handler) => {
+			if (!handler || serverToClientHandlers.get(procedure) === handler) serverToClientHandlers.delete(procedure);
+		},
+		/**
+		* Calls a NUI procedure and returns a typed Promise.
+		* The NUI must have a corresponding `onClientRpc` handler registered.
+		* Always resolves; inspect `result.success` to branch.
+		*/
+		callNuiRpc: (procedure, ...args) => {
+			const callId = generateCallId({
+				procedure,
+				channel
+			});
+			return new Promise((resolve) => {
+				const timer = setTimeout(() => {
+					clientToNuiPending.delete(callId);
+					resolve({
+						success: false,
+						error: {
+							code: "ERR_TIMEOUT",
+							procedure
+						}
+					});
+				}, timeout);
+				clientToNuiPending.set(callId, {
+					resolve,
+					timer
+				});
+				SendNuiMessage(JSON.stringify({
+					type: `__rpc_c2nui_${channel}__`,
+					callId,
+					procedure,
+					args: args[0] ?? null
+				}));
+			});
+		},
+		/** Registers a handler for a NUI-to-client RPC procedure. */
+		onNuiRpc: (procedure, handler) => {
+			nuiToClientHandlers.set(procedure, handler);
+		},
+		/** Removes a handler for a NUI-to-client RPC procedure. */
+		offNuiRpc: (procedure, handler) => {
+			if (!handler || nuiToClientHandlers.get(procedure) === handler) nuiToClientHandlers.delete(procedure);
+		}
+	};
+};
+//#endregion
+exports.initializeRpc = initializeRpc;

package/dist/nui.d.ts

@@ -0,0 +1,44 @@
+import type { NuiToClientRpc, ClientToNuiRpc, RpcPayload, RpcResult } from "./types.js";
+type InitializeRpcOptions = {
+    /**
+     * Channel name used to scope RPC events.
+     * Must match the `channel` passed to `initializeRpc` on the client.
+     * @default "default"
+     */
+    channel?: string;
+    /**
+     * Milliseconds to wait for a response before resolving with ERR_TIMEOUT.
+     * @default 10000
+     */
+    timeout?: number;
+};
+/**
+ * Initializes a NUI-side RPC channel.
+ *
+ * - {@link callClientRpc} — calls a procedure on the client script (NuiToClientRpc).
+ * - {@link onClientRpc} — registers a handler for client-initiated calls (ClientToNuiRpc).
+ *
+ * @example
+ * const { callClientRpc, onClientRpc } = initializeRpc({ channel: "ui" });
+ *
+ * onClientRpc("ui:showNotification", async ({ message }) => {
+ *     showToast(message);
+ *     return { seen: true };
+ * });
+ *
+ * const result = await callClientRpc("ui:getPlayerInfo");
+ * if (result.success) setName(result.data.name);
+ */
+export declare const initializeRpc: ({ channel, timeout, }?: InitializeRpcOptions) => {
+    /**
+     * Calls a procedure on the client script and returns a typed Promise.
+     * Always resolves; inspect `result.success` to branch.
+     */
+    callClientRpc: <Key extends keyof NuiToClientRpc>(procedure: Key, ...args: NuiToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<RpcResult<NuiToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>>;
+    /** Registers a handler for a client-to-NUI RPC procedure. */
+    onClientRpc: <Key extends keyof ClientToNuiRpc>(procedure: Key, handler: (...args: ClientToNuiRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ClientToNuiRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /** Removes a handler for a client-to-NUI RPC procedure. */
+    offClientRpc: <Key extends keyof ClientToNuiRpc>(procedure: Key, handler?: (...args: ClientToNuiRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ClientToNuiRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+};
+export {};
+//# sourceMappingURL=nui.d.ts.map

package/dist/nui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nui.d.ts","sourceRoot":"","sources":["../src/nui.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EACd,UAAU,EACV,SAAS,EAET,MAAM,YAAY,CAAC;AAUpB,KAAK,oBAAoB,GAAG;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,wBAG3B,oBAAyB;IAmD1B;;;OAGG;oBACmB,GAAG,SAAS,MAAM,cAAc,aAC1C,GAAG,WACL,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,EAAE,MAAM,IAAI,CAAC,GACnE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACN,OAAO,CACT,SAAS,CACR,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC1D,GAAG,GACH,KAAK,CACR,CACD;IAwCD,6DAA6D;kBAC/C,GAAG,SAAS,MAAM,cAAc,aAClC,GAAG,WACL,CACR,GAAG,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,EAAE,MAAM,IAAI,CAAC,GACnE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACJ,OAAO,CACX,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC1D,GAAG,GACH,KAAK,CACR;IAQF,2DAA2D;mBAC5C,GAAG,SAAS,MAAM,cAAc,aACnC,GAAG,YACJ,CACT,GAAG,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,EAAE,MAAM,IAAI,CAAC,GACnE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACJ,OAAO,CACX,cAAc,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC1D,GAAG,GACH,KAAK,CACR;CAWH,CAAC"}

package/dist/nui.js

@@ -0,0 +1,115 @@
+//#region src/nui.ts
+/** Tracks initialized channel names to prevent double-initialization. */
+const activeChannels = /* @__PURE__ */ new Set();
+/**
+* Initializes a NUI-side RPC channel.
+*
+* - {@link callClientRpc} — calls a procedure on the client script (NuiToClientRpc).
+* - {@link onClientRpc} — registers a handler for client-initiated calls (ClientToNuiRpc).
+*
+* @example
+* const { callClientRpc, onClientRpc } = initializeRpc({ channel: "ui" });
+*
+* onClientRpc("ui:showNotification", async ({ message }) => {
+*     showToast(message);
+*     return { seen: true };
+* });
+*
+* const result = await callClientRpc("ui:getPlayerInfo");
+* if (result.success) setName(result.data.name);
+*/
+const initializeRpc = ({ channel = "default", timeout = 1e4 } = {}) => {
+	if (activeChannels.has(channel)) throw new Error(`RPC channel already initialized: "${channel}"`);
+	activeChannels.add(channel);
+	const resourceName = GetParentResourceName();
+	const nuiToClientEndpoint = `https://${resourceName}/__rpc_nui2c_${channel}__`;
+	const clientToNuiResponseEndpoint = `https://${resourceName}/__rpc_c2nui_response_${channel}__`;
+	const clientToNuiHandlers = /* @__PURE__ */ new Map();
+	window.addEventListener("message", async (event) => {
+		const data = event.data;
+		if (data.type !== `__rpc_c2nui_${channel}__`) return;
+		const { callId, procedure, args } = data;
+		if (!callId || !procedure) return;
+		const handler = clientToNuiHandlers.get(procedure);
+		const result = handler ? await handler(args).then((d) => ({
+			success: true,
+			data: d
+		}), (e) => ({
+			success: false,
+			error: {
+				code: "ERR_HANDLER",
+				message: e instanceof Error ? e.message : String(e)
+			}
+		})) : {
+			success: false,
+			error: {
+				code: "ERR_NO_HANDLER",
+				procedure
+			}
+		};
+		await fetch(clientToNuiResponseEndpoint, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				callId,
+				result
+			})
+		});
+	});
+	return {
+		/**
+		* Calls a procedure on the client script and returns a typed Promise.
+		* Always resolves; inspect `result.success` to branch.
+		*/
+		callClientRpc: async (procedure, ...args) => {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeout);
+			try {
+				const response = await fetch(nuiToClientEndpoint, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						procedure,
+						args: args[0] ?? null
+					}),
+					signal: controller.signal
+				});
+				clearTimeout(timer);
+				if (!response.ok) return {
+					success: false,
+					error: {
+						code: "ERR_HANDLER",
+						message: `NUI fetch failed: ${response.status}`
+					}
+				};
+				return await response.json();
+			} catch (e) {
+				clearTimeout(timer);
+				if (e instanceof DOMException && e.name === "AbortError") return {
+					success: false,
+					error: {
+						code: "ERR_TIMEOUT",
+						procedure
+					}
+				};
+				return {
+					success: false,
+					error: {
+						code: "ERR_HANDLER",
+						message: e instanceof Error ? e.message : String(e)
+					}
+				};
+			}
+		},
+		/** Registers a handler for a client-to-NUI RPC procedure. */
+		onClientRpc: (procedure, handler) => {
+			clientToNuiHandlers.set(procedure, handler);
+		},
+		/** Removes a handler for a client-to-NUI RPC procedure. */
+		offClientRpc: (procedure, handler) => {
+			if (!handler || clientToNuiHandlers.get(procedure) === handler) clientToNuiHandlers.delete(procedure);
+		}
+	};
+};
+//#endregion
+export { initializeRpc };

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import type { ClientToServerRpc, RpcPayload, RpcResult, ServerToClientRpc } from "./types.js";
+type InitializeRpcOptions = {
+    /**
+     * Channel name used to scope RPC events.
+     * Must match the `channel` passed to `initializeRpc` on the client.
+     * @default "default"
+     */
+    channel?: string;
+    /**
+     * Timeout for S2C RPC responses in milliseconds.
+     * @default 10000
+     */
+    timeout?: number;
+};
+/**
+ * Initializes a server-side RPC channel.
+ *
+ * Each channel is isolated. Calling with the same channel name twice throws.
+ *
+ * @example
+ * const core = initializeRpc({ channel: "core" });
+ * core.onClientRpc("core:ping", async (source) => ({ pong: true }));
+ */
+export declare const initializeRpc: ({ channel, timeout, }?: InitializeRpcOptions) => {
+    /**
+     * Registers a handler for a client-to-server RPC procedure.
+     *
+     * Registering the same procedure again overwrites the previous handler.
+     *
+     * @example
+     * onClientRpc("player:getData", async (source) => ({
+     *   name: GetPlayerName(String(source)),
+     * }));
+     */
+    onClientRpc: <Key extends keyof ClientToServerRpc>(procedure: Key, handler: (source: number, ...args: ClientToServerRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ClientToServerRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /**
+     * Removes a handler for a client-to-server RPC procedure.
+     * If `handler` is provided, only removes it if it is the currently registered handler.
+     */
+    offClientRpc: <Key extends keyof ClientToServerRpc>(procedure: Key, handler?: (source: number, ...args: ClientToServerRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<ClientToServerRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>) => void;
+    /**
+     * Calls a procedure on a specific client. Always resolves; inspect `result.success` to branch.
+     */
+    callClientRpc: <Key extends keyof ServerToClientRpc>(playerId: number, procedure: Key, ...args: ServerToClientRpc[Key] extends RpcPayload<infer Req, infer _Res> ? Req extends undefined ? [] : [Req] : never) => Promise<RpcResult<ServerToClientRpc[Key] extends RpcPayload<infer _Req, infer Res> ? Res : never>>;
+};
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,iBAAiB,EAEjB,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,MAAM,YAAY,CAAC;AAgBpB,KAAK,oBAAoB,GAAG;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,wBAG3B,oBAAyB;IA8E1B;;;;;;;;;OASG;kBACW,GAAG,SAAS,MAAM,iBAAiB,aACrC,GAAG,WACL,CACR,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CACjD,MAAM,GAAG,EACT,MAAM,IAAI,CACV,GACE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACJ,OAAO,CACX,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC7D,GAAG,GACH,KAAK,CACR;IAQF;;;OAGG;mBACY,GAAG,SAAS,MAAM,iBAAiB,aACtC,GAAG,YACJ,CACT,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CACjD,MAAM,GAAG,EACT,MAAM,IAAI,CACV,GACE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACJ,OAAO,CACX,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC7D,GAAG,GACH,KAAK,CACR;IAWF;;OAEG;oBACa,GAAG,SAAS,MAAM,iBAAiB,YACxC,MAAM,aACL,GAAG,WACL,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,EAAE,MAAM,IAAI,CAAC,GACtE,GAAG,SAAS,SAAS,GACpB,EAAE,GACF,CAAC,GAAG,CAAC,GACN,KAAK,KACN,OAAO,CACT,SAAS,CACR,iBAAiB,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,IAAI,EAAE,MAAM,GAAG,CAAC,GAC7D,GAAG,GACH,KAAK,CACR,CACD;CAwBF,CAAC"}

package/dist/server.js

@@ -0,0 +1,126 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils.ts
+/** Generates a unique call ID scoped to a procedure and channel. */
+const generateCallId = ({ procedure, channel }) => `${channel}:${procedure}:${"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+	const r = Math.random() * 16 | 0;
+	return (c === "x" ? r : r & 3 | 8).toString(16);
+})}`;
+//#endregion
+//#region src/server.ts
+const activeChannels = /* @__PURE__ */ new Set();
+/**
+* Initializes a server-side RPC channel.
+*
+* Each channel is isolated. Calling with the same channel name twice throws.
+*
+* @example
+* const core = initializeRpc({ channel: "core" });
+* core.onClientRpc("core:ping", async (source) => ({ pong: true }));
+*/
+const initializeRpc = ({ channel = "default", timeout = 1e4 } = {}) => {
+	if (activeChannels.has(channel)) throw new Error(`RPC channel already initialized: "${channel}"`);
+	activeChannels.add(channel);
+	const request = `__rpc_c2s_${channel}__`;
+	const response = `__rpc_c2s_response_${channel}__`;
+	const clientToServerHandlers = /* @__PURE__ */ new Map();
+	const onRpcRequest = (handler) => onNet(request, handler);
+	const emitRpcResponse = ({ target, callId, result }) => emitNet(response, target, callId, result);
+	onRpcRequest(async (callId, procedure, args) => {
+		const playerId = source;
+		const handler = clientToServerHandlers.get(procedure);
+		if (!handler) {
+			emitRpcResponse({
+				target: playerId,
+				callId,
+				result: {
+					success: false,
+					error: {
+						code: "ERR_NO_HANDLER",
+						procedure
+					}
+				}
+			});
+			return;
+		}
+		try {
+			emitRpcResponse({
+				target: playerId,
+				callId,
+				result: {
+					success: true,
+					data: await handler(playerId, args)
+				}
+			});
+		} catch (e) {
+			emitRpcResponse({
+				target: playerId,
+				callId,
+				result: {
+					success: false,
+					error: {
+						code: "ERR_HANDLER",
+						message: e instanceof Error ? e.message : String(e)
+					}
+				}
+			});
+		}
+	});
+	const serverToClientPending = /* @__PURE__ */ new Map();
+	onNet(`__rpc_s2c_response_${channel}__`, (callId, result) => {
+		const pending = serverToClientPending.get(callId);
+		if (!pending) return;
+		serverToClientPending.delete(callId);
+		clearTimeout(pending.timer);
+		pending.resolve(result);
+	});
+	return {
+		/**
+		* Registers a handler for a client-to-server RPC procedure.
+		*
+		* Registering the same procedure again overwrites the previous handler.
+		*
+		* @example
+		* onClientRpc("player:getData", async (source) => ({
+		*   name: GetPlayerName(String(source)),
+		* }));
+		*/
+		onClientRpc: (procedure, handler) => {
+			clientToServerHandlers.set(procedure, handler);
+		},
+		/**
+		* Removes a handler for a client-to-server RPC procedure.
+		* If `handler` is provided, only removes it if it is the currently registered handler.
+		*/
+		offClientRpc: (procedure, handler) => {
+			if (!handler || clientToServerHandlers.get(procedure) === handler) clientToServerHandlers.delete(procedure);
+		},
+		/**
+		* Calls a procedure on a specific client. Always resolves; inspect `result.success` to branch.
+		*/
+		callClientRpc: (playerId, procedure, ...args) => {
+			const callId = generateCallId({
+				procedure,
+				channel
+			});
+			return new Promise((resolve) => {
+				const timer = setTimeout(() => {
+					serverToClientPending.delete(callId);
+					resolve({
+						success: false,
+						error: {
+							code: "ERR_TIMEOUT",
+							procedure
+						}
+					});
+				}, timeout);
+				serverToClientPending.set(callId, {
+					resolve,
+					timer
+				});
+				emitNet(`__rpc_s2c_${channel}__`, playerId, callId, procedure, args[0] ?? null);
+			});
+		}
+	};
+};
+//#endregion
+exports.initializeRpc = initializeRpc;

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Registry of client-to-server RPC procedures.
+ *
+ * @example
+ * declare module "fivem-rpc/types" {
+ *   interface ClientToServerRpc {
+ *     "player:getData": RpcPayload<undefined, { name: string }>;
+ *   }
+ * }
+ */
+export interface ClientToServerRpc {
+}
+/**
+ * Registry of server-to-client RPC procedures.
+ *
+ * @example
+ * declare module "fivem-rpc/types" {
+ *   interface ServerToClientRpc {
+ *     "player:showNotification": RpcPayload<{ message: string }, { seen: boolean }>;
+ *   }
+ * }
+ */
+export interface ServerToClientRpc {
+}
+/**
+ * Registry of NUI-to-client RPC procedures (NUI calls client script).
+ *
+ * @example
+ * declare module "fivem-rpc/types" {
+ *   interface NuiToClientRpc {
+ *     "ui:getPlayerInfo": RpcPayload<undefined, { name: string }>;
+ *   }
+ * }
+ */
+export interface NuiToClientRpc {
+}
+/**
+ * Registry of client-to-NUI RPC procedures (client script calls NUI).
+ *
+ * @example
+ * declare module "fivem-rpc/types" {
+ *   interface ClientToNuiRpc {
+ *     "ui:showNotification": RpcPayload<{ message: string }, { seen: boolean }>;
+ *   }
+ * }
+ */
+export interface ClientToNuiRpc {
+}
+/**
+ * Describes the request and response types for a single RPC procedure.
+ *
+ * @example
+ * "player:setJob": RpcPayload<{ job: string }, { ok: boolean }>
+ * "player:ping":   RpcPayload<undefined, undefined>
+ */
+export type RpcPayload<Request extends Record<string, unknown> | undefined = undefined, Response extends Record<string, unknown> | undefined = undefined> = {
+    request: Request;
+    response: Response;
+};
+/**
+ * Returned by all RPC call functions. Narrow on `success` before accessing `data` or `error`.
+ *
+ * @example
+ * const result = await callServerRpc("player:getData");
+ * if (result.success) console.log(result.data.name);
+ * else if (result.error.code === "ERR_TIMEOUT") console.warn("timed out");
+ */
+export type RpcResult<T> = {
+    success: true;
+    data: T;
+    error?: never;
+} | {
+    success: false;
+    data?: never;
+    error: RpcError;
+};
+/**
+ * Discriminated error union returned in `RpcResult` on failure.
+ *
+ * - `ERR_NO_HANDLER`: no handler registered for the procedure
+ * - `ERR_TIMEOUT`: response not received within the timeout
+ * - `ERR_HANDLER`: handler threw at runtime
+ */
+export type RpcError = {
+    code: "ERR_NO_HANDLER";
+    procedure: string;
+} | {
+    code: "ERR_TIMEOUT";
+    procedure: string;
+} | {
+    code: "ERR_HANDLER";
+    message: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;CAAG;AAErC;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;CAAG;AAErC;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;CAAG;AAElC;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;CAAG;AAElC;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CACrB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EAC/D,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,IAC7D;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACpB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACzC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+/** Generates a unique call ID scoped to a procedure and channel. */
+export declare const generateCallId: ({ procedure, channel, }: {
+    procedure: string;
+    channel: string;
+}) => string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,eAAO,MAAM,cAAc,GAAI,yBAG5B;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB,KAAG,MASA,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "fivem-rpc",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A TypeScript library for creating type-safe RPCs in FiveM.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carlos-menezes/fivem-rpc"
+  },
+  "author": "Carlos Menezes",
+  "license": "MIT",
+  "exports": {
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./nui": {
+      "types": "./dist/nui.d.ts",
+      "default": "./dist/nui.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@changesets/cli": "^2.31.0",
+    "@citizenfx/client": "^2.0.29753-1",
+    "@citizenfx/server": "^2.0.29753-1",
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "happy-dom": "^20.9.0",
+    "husky": "^9.1.7",
+    "rolldown": "^1.0.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "peerDependencies": {
+    "@citizenfx/client": "^2.0.29753-1",
+    "@citizenfx/server": "^2.0.29753-1"
+  },
+  "scripts": {
+    "build": "rolldown --config rolldown.config.ts && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "biome format --write",
+    "lint": "biome lint --write",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
+  }
+}