rbxts-trpc 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Mergemat
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# rbxts-trpc
+
+Type-safe tRPC-style procedures and events for Roblox TS, built on top of `@rbxts/remo`.
+
+## Docs
+
+- Live docs: https://rbxts-trpc.vercel.app
+- Source docs app: `docs/`
+
+Everything else (guides, API reference, React usage, events/procedures, and LLM endpoints) lives in the docs site.
+
+## Install
+
+```sh
+bun add rbxts-trpc @rbxts/remo @rbxts/t
+```
+
+If you use React helpers, also install `@rbxts/react`.
+
+## Quick Example
+
+```ts
+import { t as v } from "@rbxts/t";
+import { createClient, createServer, initTRPC } from "rbxts-trpc";
+
+const trpc = initTRPC()
+	.context<{ player?: Player }>()
+	.create({
+		createContext: ({ player }) => ({ player }),
+	});
+
+const appRouter = trpc.router({
+	todos: trpc.router({
+		list: trpc.procedure
+			.intent("query")
+			.output<string[]>(v.array(v.string))
+			.resolve(() => ["Milk", "Eggs"]),
+		add: trpc.procedure.input<string>(v.string).resolve(({ input }) => input.size() > 0),
+		changed: trpc.event.client.input<string[]>(v.array(v.string)).create(),
+	}),
+});
+
+const server = createServer({ t: trpc, router: appRouter });
+server.events.todos.changed.emitAll(["Milk", "Eggs", "Bread"]);
+
+const client = createClient({ t: trpc, router: appRouter });
+client.todos.list.query(undefined).then((todos) => print(todos.size()));
+```
+
+## Develop
+
+```sh
+bun run build
+bun run lint
+bun run docs:dev
+```

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./out/index";

package/out/client/createClient.d.ts

@@ -0,0 +1,11 @@
+import type { TRPCFactory } from "../core/initTRPC";
+import type { ClientEvent, ClientEventProxy, Procedure, ProcedureCallProxy, Router, RouterShape, ServerEvent, ServerEventProxy } from "../core/types";
+type ClientShapeFromRouter<TRouter extends Router<any, RouterShape<any>>> = ClientShapeFromNodes<TRouter["_def"]["shape"]>;
+type ClientShapeFromNodes<TShape> = {
+    [K in keyof TShape]: TShape[K] extends Router<any, any> ? ClientShapeFromNodes<TShape[K]["_def"]["shape"]> : TShape[K] extends Procedure<any, infer TInput, infer TOutput, infer TIntent> ? ProcedureCallProxy<TInput, TOutput, TIntent> : TShape[K] extends ServerEvent<any, infer TInput> ? ServerEventProxy<TInput> : TShape[K] extends ClientEvent<any, infer TInput> ? ClientEventProxy<TInput> : never;
+};
+export declare function createClient<TContext, TRouter extends Router<TContext, RouterShape<TContext>>>(options: {
+    t: TRPCFactory<TContext>;
+    router: TRouter;
+}): ClientShapeFromRouter<TRouter>;
+export {};

package/out/client/createClient.luau

@@ -0,0 +1,135 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createRemotes = TS.import(script, TS.getModule(script, "@rbxts", "remo").src).createRemotes
+local _errors = TS.import(script, script.Parent.Parent, "core", "errors")
+local TRPCClientError = _errors.TRPCClientError
+local toErrorShape = _errors.toErrorShape
+local _execute = TS.import(script, script.Parent.Parent, "runtime", "execute")
+local formatError = _execute.formatError
+local runClientEvent = _execute.runClientEvent
+local _schema = TS.import(script, script.Parent.Parent, "runtime", "schema")
+local buildRemoSchema = _schema.buildRemoSchema
+local joinPath = _schema.joinPath
+local function isRouterNode(node)
+	return node._def.kind == "router"
+end
+local function isProcedureNode(node)
+	return node._def.kind == "procedure"
+end
+local function isServerEventNode(node)
+	return node._def.kind == "event" and node._def.direction == "server"
+end
+local function isClientEventNode(node)
+	return node._def.kind == "event" and node._def.direction == "client"
+end
+local function createClient(options)
+	local schema = buildRemoSchema(options.router)
+	local remotes = createRemotes(schema)
+	local listenersByPath = {}
+	local addListener = function(path, listener)
+		local listeners = listenersByPath[path] or {}
+		local _listener = listener
+		table.insert(listeners, _listener)
+		listenersByPath[path] = listeners
+		return function()
+			local current = listenersByPath[path]
+			if not current then
+				return nil
+			end
+			local _listener_1 = listener
+			local index = (table.find(current, _listener_1) or 0) - 1
+			if index >= 0 then
+				table.remove(current, index + 1)
+			end
+		end
+	end
+	local walk
+	walk = function(shape, remoteShape, target, parent)
+		for key, rawNode in pairs(shape) do
+			local keyName = key
+			local node = rawNode
+			local path = joinPath(parent, keyName)
+			local remoteNode = remoteShape[keyName]
+			if isRouterNode(node) then
+				local nested = {}
+				target[keyName] = nested
+				walk(node._def.shape, remoteNode, nested, path)
+				continue
+			end
+			if isProcedureNode(node) then
+				local execute = TS.async(function(input)
+					local requestRemote = remoteNode
+					local result
+					TS.try(function()
+						result = TS.await(requestRemote.request(requestRemote, input))
+					end, function(caught)
+						local shape = formatError(options.t._config, caught)
+						error(TRPCClientError.new(shape))
+					end)
+					if not result.ok then
+						error(TRPCClientError.new(result.error))
+					end
+					return result.data
+				end)
+				local _object = {
+					__kind = "procedure",
+					__path = path,
+					__intent = node._def.intent,
+				}
+				for _k, _v in (if node._def.intent == "query" then {
+					query = execute,
+				} else {
+					mutate = execute,
+				}) do
+					_object[_k] = _v
+				end
+				target[keyName] = _object
+				continue
+			end
+			if isServerEventNode(node) then
+				target[keyName] = {
+					__kind = "serverEvent",
+					__path = path,
+					emit = function(input)
+						local fireRemote = remoteNode
+						fireRemote.fire(fireRemote, input)
+					end,
+				}
+				continue
+			end
+			if isClientEventNode(node) then
+				local connectRemote = remoteNode
+				connectRemote.connect(connectRemote, function(input)
+					task.spawn(TS.async(function()
+						local listeners = listenersByPath[path] or {}
+						TS.try(function()
+							TS.await(runClientEvent({
+								config = options.t._config,
+								path = path,
+								input = input,
+								inputValidator = node._def.inputValidator,
+								middlewares = node._def.middlewares,
+								listeners = listeners,
+							}))
+						end, function(caught)
+							warn(`[rbxts-trpc] client event error on '{path}':`, toErrorShape(caught))
+						end)
+					end))
+				end)
+				target[keyName] = {
+					__kind = "clientEvent",
+					__path = path,
+					on = function(listener)
+						return addListener(path, listener)
+					end,
+				}
+			end
+		end
+	end
+	local client = {}
+	walk(options.router._def.shape, remotes, client)
+	return client
+end
+return {
+	createClient = createClient,
+}

package/out/core/errors.d.ts

@@ -0,0 +1,15 @@
+import type { ErrorShape, TRPCErrorCode } from "./types";
+export declare class TRPCError {
+    readonly name = "TRPCError";
+    readonly code: TRPCErrorCode;
+    readonly message: string;
+    readonly data?: unknown;
+    constructor(code: TRPCErrorCode, message: string, data?: unknown);
+}
+export declare class TRPCClientError {
+    readonly name = "TRPCClientError";
+    readonly message: string;
+    readonly shape: ErrorShape;
+    constructor(shape: ErrorShape);
+}
+export declare function toErrorShape(caught: unknown): ErrorShape;

package/out/core/errors.luau

@@ -0,0 +1,69 @@
+-- Compiled with roblox-ts v3.0.0
+local TRPCError
+do
+	TRPCError = setmetatable({}, {
+		__tostring = function()
+			return "TRPCError"
+		end,
+	})
+	TRPCError.__index = TRPCError
+	function TRPCError.new(...)
+		local self = setmetatable({}, TRPCError)
+		return self:constructor(...) or self
+	end
+	function TRPCError:constructor(code, message, data)
+		self.name = "TRPCError"
+		self.code = code
+		self.message = message
+		self.data = data
+	end
+end
+local TRPCClientError
+do
+	TRPCClientError = setmetatable({}, {
+		__tostring = function()
+			return "TRPCClientError"
+		end,
+	})
+	TRPCClientError.__index = TRPCClientError
+	function TRPCClientError.new(...)
+		local self = setmetatable({}, TRPCClientError)
+		return self:constructor(...) or self
+	end
+	function TRPCClientError:constructor(shape)
+		self.name = "TRPCClientError"
+		self.shape = shape
+		self.message = shape.message
+	end
+end
+local function toErrorShape(caught)
+	local _caught = caught
+	if type(_caught) == "table" then
+		local maybeError = caught
+		local _code = maybeError.code
+		local _condition = type(_code) == "string"
+		if _condition then
+			local _message = maybeError.message
+			_condition = type(_message) == "string"
+		end
+		if _condition then
+			return {
+				code = maybeError.code,
+				message = maybeError.message,
+				data = maybeError.data,
+			}
+		end
+	end
+	local _object = {
+		code = "INTERNAL_SERVER_ERROR",
+	}
+	local _left = "message"
+	local _caught_1 = caught
+	_object[_left] = if type(_caught_1) == "string" then caught else "Internal server error"
+	return _object
+end
+return {
+	toErrorShape = toErrorShape,
+	TRPCError = TRPCError,
+	TRPCClientError = TRPCClientError,
+}

package/out/core/event.d.ts

@@ -0,0 +1,23 @@
+import type { ClientEvent, EventHandler, EventMiddleware, ServerEvent, Validator } from "./types";
+export declare class ServerEventBuilder<TContext, TInput> {
+    private readonly currentInputValidator?;
+    private readonly currentMiddlewares;
+    constructor(options?: {
+        inputValidator?: Validator<TInput>;
+        middlewares?: ReadonlyArray<EventMiddleware<TContext, TInput>>;
+    });
+    input<TNextInput>(validator: Validator<TNextInput>): ServerEventBuilder<TContext, TNextInput>;
+    use(middleware: EventMiddleware<TContext, TInput>): ServerEventBuilder<TContext, TInput>;
+    handle(handler: EventHandler<TContext, TInput>): ServerEvent<TContext, TInput>;
+}
+export declare class ClientEventBuilder<TContext, TInput> {
+    private readonly currentInputValidator?;
+    private readonly currentMiddlewares;
+    constructor(options?: {
+        inputValidator?: Validator<TInput>;
+        middlewares?: ReadonlyArray<EventMiddleware<TContext, TInput>>;
+    });
+    input<TNextInput>(validator: Validator<TNextInput>): ClientEventBuilder<TContext, TNextInput>;
+    use(middleware: EventMiddleware<TContext, TInput>): ClientEventBuilder<TContext, TInput>;
+    create(): ClientEvent<TContext, TInput>;
+}

package/out/core/event.luau

@@ -0,0 +1,154 @@
+-- Compiled with roblox-ts v3.0.0
+local ServerEventImpl
+do
+	ServerEventImpl = setmetatable({}, {
+		__tostring = function()
+			return "ServerEventImpl"
+		end,
+	})
+	ServerEventImpl.__index = ServerEventImpl
+	function ServerEventImpl.new(...)
+		local self = setmetatable({}, ServerEventImpl)
+		return self:constructor(...) or self
+	end
+	function ServerEventImpl:constructor(def)
+		self._def = def
+	end
+end
+local ClientEventImpl
+do
+	ClientEventImpl = setmetatable({}, {
+		__tostring = function()
+			return "ClientEventImpl"
+		end,
+	})
+	ClientEventImpl.__index = ClientEventImpl
+	function ClientEventImpl.new(...)
+		local self = setmetatable({}, ClientEventImpl)
+		return self:constructor(...) or self
+	end
+	function ClientEventImpl:constructor(def)
+		self._def = def
+	end
+end
+local ServerEventBuilder
+do
+	ServerEventBuilder = setmetatable({}, {
+		__tostring = function()
+			return "ServerEventBuilder"
+		end,
+	})
+	ServerEventBuilder.__index = ServerEventBuilder
+	function ServerEventBuilder.new(...)
+		local self = setmetatable({}, ServerEventBuilder)
+		return self:constructor(...) or self
+	end
+	function ServerEventBuilder:constructor(options)
+		local _result = options
+		if _result ~= nil then
+			_result = _result.inputValidator
+		end
+		self.currentInputValidator = _result
+		local _result_1 = options
+		if _result_1 ~= nil then
+			_result_1 = _result_1.middlewares
+		end
+		local _condition = _result_1
+		if _condition == nil then
+			_condition = {}
+		end
+		self.currentMiddlewares = _condition
+	end
+	function ServerEventBuilder:input(validator)
+		return ServerEventBuilder.new({
+			inputValidator = validator,
+			middlewares = self.currentMiddlewares,
+		})
+	end
+	function ServerEventBuilder:use(middleware)
+		local _object = {
+			inputValidator = self.currentInputValidator,
+		}
+		local _left = "middlewares"
+		local _array = {}
+		local _length = #_array
+		local _array_1 = self.currentMiddlewares
+		local _Length = #_array_1
+		table.move(_array_1, 1, _Length, _length + 1, _array)
+		_length += _Length
+		_array[_length + 1] = middleware
+		_object[_left] = _array
+		return ServerEventBuilder.new(_object)
+	end
+	function ServerEventBuilder:handle(handler)
+		return ServerEventImpl.new({
+			kind = "event",
+			direction = "server",
+			inputValidator = self.currentInputValidator,
+			middlewares = self.currentMiddlewares,
+			handle = handler,
+		})
+	end
+end
+local ClientEventBuilder
+do
+	ClientEventBuilder = setmetatable({}, {
+		__tostring = function()
+			return "ClientEventBuilder"
+		end,
+	})
+	ClientEventBuilder.__index = ClientEventBuilder
+	function ClientEventBuilder.new(...)
+		local self = setmetatable({}, ClientEventBuilder)
+		return self:constructor(...) or self
+	end
+	function ClientEventBuilder:constructor(options)
+		local _result = options
+		if _result ~= nil then
+			_result = _result.inputValidator
+		end
+		self.currentInputValidator = _result
+		local _result_1 = options
+		if _result_1 ~= nil then
+			_result_1 = _result_1.middlewares
+		end
+		local _condition = _result_1
+		if _condition == nil then
+			_condition = {}
+		end
+		self.currentMiddlewares = _condition
+	end
+	function ClientEventBuilder:input(validator)
+		return ClientEventBuilder.new({
+			inputValidator = validator,
+			middlewares = self.currentMiddlewares,
+		})
+	end
+	function ClientEventBuilder:use(middleware)
+		local _object = {
+			inputValidator = self.currentInputValidator,
+		}
+		local _left = "middlewares"
+		local _array = {}
+		local _length = #_array
+		local _array_1 = self.currentMiddlewares
+		local _Length = #_array_1
+		table.move(_array_1, 1, _Length, _length + 1, _array)
+		_length += _Length
+		_array[_length + 1] = middleware
+		_object[_left] = _array
+		return ClientEventBuilder.new(_object)
+	end
+	function ClientEventBuilder:create()
+		return ClientEventImpl.new({
+			kind = "event",
+			direction = "client",
+			inputValidator = self.currentInputValidator,
+			middlewares = self.currentMiddlewares,
+		})
+	end
+end
+return {
+	ServerEventBuilder = ServerEventBuilder,
+	ClientEventBuilder = ClientEventBuilder,
+}

package/out/core/initTRPC.d.ts

@@ -0,0 +1,28 @@
+import { ClientEventBuilder, ServerEventBuilder } from "./event";
+import { ProcedureBuilder } from "./procedure";
+import type { InitTRPCConfig, Router, RouterShape } from "./types";
+export interface TRPCFactory<TContext> {
+    readonly _config: InitTRPCConfig<TContext>;
+    readonly procedure: ProcedureBuilder<TContext, undefined, unknown, "mutation">;
+    readonly event: {
+        readonly server: ServerEventBuilder<TContext, undefined>;
+        readonly client: ClientEventBuilder<TContext, undefined>;
+    };
+    router<TShape extends RouterShape<TContext>>(shape: TShape): Router<TContext, TShape>;
+}
+declare class FactoryImpl<TContext> implements TRPCFactory<TContext> {
+    readonly _config: InitTRPCConfig<TContext>;
+    readonly procedure: ProcedureBuilder<TContext, undefined, unknown, "mutation">;
+    readonly event: {
+        server: ServerEventBuilder<TContext, undefined>;
+        client: ClientEventBuilder<TContext, undefined>;
+    };
+    constructor(config: InitTRPCConfig<TContext>);
+    router<TShape extends RouterShape<TContext>>(shape: TShape): Router<TContext, TShape>;
+}
+export declare function initTRPC(): {
+    context<TContext>(): {
+        create(config?: InitTRPCConfig<TContext>): FactoryImpl<TContext>;
+    };
+};
+export {};

package/out/core/initTRPC.luau

@@ -0,0 +1,48 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _event = TS.import(script, script.Parent, "event")
+local ClientEventBuilder = _event.ClientEventBuilder
+local ServerEventBuilder = _event.ServerEventBuilder
+local ProcedureBuilder = TS.import(script, script.Parent, "procedure").ProcedureBuilder
+local createRouter = TS.import(script, script.Parent, "router").createRouter
+local FactoryImpl
+do
+	FactoryImpl = setmetatable({}, {
+		__tostring = function()
+			return "FactoryImpl"
+		end,
+	})
+	FactoryImpl.__index = FactoryImpl
+	function FactoryImpl.new(...)
+		local self = setmetatable({}, FactoryImpl)
+		return self:constructor(...) or self
+	end
+	function FactoryImpl:constructor(config)
+		self.procedure = ProcedureBuilder.new()
+		self.event = {
+			server = ServerEventBuilder.new(),
+			client = ClientEventBuilder.new(),
+		}
+		self._config = config
+	end
+	function FactoryImpl:router(shape)
+		return createRouter(shape)
+	end
+end
+local function initTRPC()
+	return {
+		context = function(self)
+			return {
+				create = function(self, config)
+					if config == nil then
+						config = {}
+					end
+					return FactoryImpl.new(config)
+				end,
+			}
+		end,
+	}
+end
+return {
+	initTRPC = initTRPC,
+}

package/out/core/procedure.d.ts

@@ -0,0 +1,18 @@
+import type { Procedure, ProcedureIntent, ProcedureMiddleware, ProcedureResolver, Validator } from "./types";
+export declare class ProcedureBuilder<TContext, TInput, TOutput, TIntent extends ProcedureIntent = "mutation"> {
+    private readonly inputValidator?;
+    private readonly outputValidator?;
+    private readonly middlewares;
+    private readonly currentIntent;
+    constructor(options?: {
+        inputValidator?: Validator<TInput>;
+        outputValidator?: Validator<TOutput>;
+        middlewares?: ReadonlyArray<ProcedureMiddleware<TContext, TInput, TOutput>>;
+        intent?: TIntent;
+    });
+    input<TNextInput>(validator: Validator<TNextInput>): ProcedureBuilder<TContext, TNextInput, TOutput, TIntent>;
+    output<TNextOutput>(validator: Validator<TNextOutput>): ProcedureBuilder<TContext, TInput, TNextOutput, TIntent>;
+    use(middleware: ProcedureMiddleware<TContext, TInput, TOutput>): ProcedureBuilder<TContext, TInput, TOutput, TIntent>;
+    intent<TNextIntent extends ProcedureIntent>(intent: TNextIntent): ProcedureBuilder<TContext, TInput, TOutput, TNextIntent>;
+    resolve<TResolvedOutput extends TOutput>(resolve: ProcedureResolver<TContext, TInput, TResolvedOutput>): Procedure<TContext, TInput, TResolvedOutput, TIntent>;
+}

package/out/core/procedure.luau

@@ -0,0 +1,115 @@
+-- Compiled with roblox-ts v3.0.0
+local ProcedureImpl
+do
+	ProcedureImpl = setmetatable({}, {
+		__tostring = function()
+			return "ProcedureImpl"
+		end,
+	})
+	ProcedureImpl.__index = ProcedureImpl
+	function ProcedureImpl.new(...)
+		local self = setmetatable({}, ProcedureImpl)
+		return self:constructor(...) or self
+	end
+	function ProcedureImpl:constructor(def)
+		self._def = def
+	end
+end
+local ProcedureBuilder
+do
+	ProcedureBuilder = setmetatable({}, {
+		__tostring = function()
+			return "ProcedureBuilder"
+		end,
+	})
+	ProcedureBuilder.__index = ProcedureBuilder
+	function ProcedureBuilder.new(...)
+		local self = setmetatable({}, ProcedureBuilder)
+		return self:constructor(...) or self
+	end
+	function ProcedureBuilder:constructor(options)
+		local _result = options
+		if _result ~= nil then
+			_result = _result.inputValidator
+		end
+		self.inputValidator = _result
+		local _result_1 = options
+		if _result_1 ~= nil then
+			_result_1 = _result_1.outputValidator
+		end
+		self.outputValidator = _result_1
+		local _result_2 = options
+		if _result_2 ~= nil then
+			_result_2 = _result_2.middlewares
+		end
+		local _condition = _result_2
+		if _condition == nil then
+			_condition = {}
+		end
+		self.middlewares = _condition
+		local _result_3 = options
+		if _result_3 ~= nil then
+			_result_3 = _result_3.intent
+		end
+		local _condition_1 = _result_3
+		if _condition_1 == nil then
+			_condition_1 = "mutation"
+		end
+		self.currentIntent = _condition_1
+	end
+	function ProcedureBuilder:input(validator)
+		return ProcedureBuilder.new({
+			inputValidator = validator,
+			outputValidator = self.outputValidator,
+			middlewares = self.middlewares,
+			intent = self.currentIntent,
+		})
+	end
+	function ProcedureBuilder:output(validator)
+		return ProcedureBuilder.new({
+			inputValidator = self.inputValidator,
+			outputValidator = validator,
+			middlewares = self.middlewares,
+			intent = self.currentIntent,
+		})
+	end
+	function ProcedureBuilder:use(middleware)
+		local _object = {
+			inputValidator = self.inputValidator,
+			outputValidator = self.outputValidator,
+		}
+		local _left = "middlewares"
+		local _array = {}
+		local _length = #_array
+		local _array_1 = self.middlewares
+		local _Length = #_array_1
+		table.move(_array_1, 1, _Length, _length + 1, _array)
+		_length += _Length
+		_array[_length + 1] = middleware
+		_object[_left] = _array
+		_object.intent = self.currentIntent
+		return ProcedureBuilder.new(_object)
+	end
+	function ProcedureBuilder:intent(intent)
+		return ProcedureBuilder.new({
+			inputValidator = self.inputValidator,
+			outputValidator = self.outputValidator,
+			middlewares = self.middlewares,
+			intent = intent,
+		})
+	end
+	function ProcedureBuilder:resolve(resolve)
+		local def = {
+			kind = "procedure",
+			intent = self.currentIntent,
+			inputValidator = self.inputValidator,
+			outputValidator = self.outputValidator,
+			middlewares = self.middlewares,
+			resolve = resolve,
+		}
+		return ProcedureImpl.new(def)
+	end
+end
+return {
+	ProcedureBuilder = ProcedureBuilder,
+}