Unary Methods

Unary methods handle a single request and return a single response — the most common RPC pattern.

Basic usage

import { Protocol, float } from "@query-farm/vgi-rpc";

const protocol = new Protocol("MyService");

protocol.unary("add", {
  params: { a: float, b: float },
  result: { result: float },
  handler: async ({ a, b }) => ({ result: a + b }),
  doc: "Add two numbers.",
});

Handler signature

The handler receives two arguments:

type UnaryHandler = (
  params: Record<string, any>,
  ctx: LogContext,
) => Promise<Record<string, any>> | Record<string, any>;

• params — parsed parameter values from the request, keyed by field name
• ctx — provides clientLog() for client-directed logging

The handler must return an object matching the result schema. It can be sync or async.

Default values

Provide default values for optional parameters with the defaults field:

protocol.unary("add", {
  params: { a: float, b: float },
  result: { result: float },
  handler: async ({ a, b }) => ({ result: a + b }),
  defaults: { b: 1.0 },
});

When the client omits b, it defaults to 1.0.

Documentation strings

The doc field is exposed through the __describe__ introspection method:

protocol.unary("greet", {
  params: { name: str },
  result: { greeting: str },
  handler: async ({ name }) => ({ greeting: `Hello, ${name}!` }),
  doc: "Greet someone by name.",
});

Clients can discover method documentation by calling vgi-rpc describe.

Parameter type hints

By default, vgi-rpc infers Python-style parameter type strings from the params schema (for example int, float, str). To override or supplement these hints — for instance when a field uses a complex Arrow type that cannot be inferred — provide the optional paramTypes field:

protocol.unary("scale", {
  params: { value: float },
  result: { result: float },
  handler: async ({ value }) => ({ result: value * 2 }),
  paramTypes: { value: "float" },
});

When omitted, paramTypes is derived automatically via inferParamTypes(params).

Error handling

Throw any Error from a handler to propagate it to the client:

protocol.unary("divide", {
  params: { a: float, b: float },
  result: { result: float },
  handler: async ({ a, b }) => {
    if (b === 0) throw new Error("Division by zero");
    return { result: a / b };
  },
});

See Error Handling for more details.