Schema Shorthand

vgi-rpc provides shorthand type singletons that eliminate boilerplate when declaring parameter, result, and output schemas.

Using shorthand

Instead of constructing Schema and Field objects manually, use the shorthand syntax:

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

protocol.unary("echo", {
  params: { name: str, count: int, value: float },
  result: { result: str },
  handler: ({ name }) => ({ result: name }),
});

This is equivalent to the verbose form:

import { Schema, Field, Utf8, Int64, Float64 } from "@query-farm/apache-arrow";

protocol.unary("echo", {
  params: new Schema([
    new Field("name", new Utf8(), false),
    new Field("count", new Int64(), false),
    new Field("value", new Float64(), false),
  ]),
  result: new Schema([new Field("result", new Utf8(), false)]),
  handler: ({ name }) => ({ result: name }),
});

Available type singletons

Singleton	Arrow Type	Python equivalent
str	Utf8	str
bytes	Binary	bytes
bool	Bool	bool
int	Int64	int
int8	Int8	Annotated[int, ArrowType(pa.int8())]
int16	Int16	Annotated[int, ArrowType(pa.int16())]
int32	Int32	Annotated[int, ArrowType(pa.int32())]
uint8	Uint8	Annotated[int, ArrowType(pa.uint8())]
uint16	Uint16	Annotated[int, ArrowType(pa.uint16())]
uint32	Uint32	Annotated[int, ArrowType(pa.uint32())]
uint64	Uint64	Annotated[int, ArrowType(pa.uint64())]
float	Float64	float
float32	Float32	Annotated[float, ArrowType(pa.float32())]

The SchemaLike type

Methods accept a full Schema object, anything structurally schema-shaped, or a record mapping field names to a DataType or a Field:

type SchemaLike = Schema | SchemaShape | Record<string, DataType | Field>;

A record value may be a bare DataType (in which case the field is created non-nullable) or a fully-constructed Field (when you need control over nullability or per-field metadata). The toSchema() function converts any SchemaLike into a proper Arrow Schema.

Complex types

For types not covered by the singletons — List, Map, Dictionary, Struct, or nullable fields — use the full Schema/Field constructors from @query-farm/apache-arrow:

import { Schema, Field, List, Utf8 } from "@query-farm/apache-arrow";

protocol.unary("tags", {
  params: new Schema([
    new Field("tags", new List(new Field("item", new Utf8(), false)), false),
  ]),
  result: { count: int },
  handler: ({ tags }) => ({ count: tags.length }),
});

You can mix shorthand and full schemas — use shorthand where it fits and full schemas where you need more control.