@query-farm/vgi-rpc 0.2.3 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,19 +1,15 @@
|
|
|
1
|
-
|
|
2
|
-
<a href="https://vgi-rpc.query.farm">
|
|
3
|
-
<img src="https://vgi-rpc.query.farm/logo-hero.png" alt="VGI — The Vector Gateway Interface" width="200">
|
|
4
|
-
</a>
|
|
5
|
-
</p>
|
|
1
|
+
[](https://vgi-rpc.query.farm)
|
|
6
2
|
|
|
7
3
|
# vgi-rpc
|
|
8
4
|
|
|
9
5
|
TypeScript server library for the [vgi-rpc](https://vgi-rpc.query.farm) framework. Implements RPC servers that communicate over stdin/stdout using [Apache Arrow](https://arrow.apache.org/) IPC serialization.
|
|
10
6
|
|
|
11
|
-
Define RPC methods with Arrow-typed schemas, serve them over stdin/stdout, and interact with them using the Python `vgi-rpc` CLI or any vgi-rpc client. Unlike JSON-over-HTTP, structured data stays in Arrow columnar format for efficient transfer.
|
|
7
|
+
Define RPC methods with Arrow-typed schemas, serve them over stdin/stdout, and interact with them using the Python `vgi-rpc` CLI or any `vgi-rpc` client. Unlike JSON-over-HTTP, structured data stays in Arrow columnar format for efficient transfer.
|
|
12
8
|
|
|
13
9
|
**Key features:**
|
|
14
10
|
|
|
15
11
|
- **Three method types** — unary (request-response), producer (server-streaming), and exchange (bidirectional-streaming)
|
|
16
|
-
- **Apache Arrow IPC wire format** — efficient columnar serialization compatible with the Python vgi-rpc framework
|
|
12
|
+
- **Apache Arrow IPC wire format** — efficient columnar serialization compatible with the Python `vgi-rpc` framework
|
|
17
13
|
- **Schema shorthand** — declare schemas with `{ name: str, count: int }` instead of manual `Schema`/`Field` construction
|
|
18
14
|
- **Fluent protocol builder** — chain `.unary()`, `.producer()`, `.exchange()` calls to define your service
|
|
19
15
|
- **Type-safe streaming state** — generic `<S>` parameter threads state types through init and produce/exchange functions
|
|
@@ -24,10 +20,32 @@ Define RPC methods with Arrow-typed schemas, serve them over stdin/stdout, and i
|
|
|
24
20
|
## Installation
|
|
25
21
|
|
|
26
22
|
```bash
|
|
23
|
+
# Bun
|
|
27
24
|
bun add @query-farm/vgi-rpc
|
|
25
|
+
|
|
26
|
+
# npm
|
|
27
|
+
npm install @query-farm/vgi-rpc
|
|
28
|
+
|
|
29
|
+
# Deno
|
|
30
|
+
deno add npm:@query-farm/vgi-rpc
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Runtime Compatibility
|
|
34
|
+
|
|
35
|
+
`vgi-rpc` works with [Bun](https://bun.sh/), [Node.js](https://nodejs.org/) 22+, and [Deno](https://deno.land/) 2+. The HTTP handler and HTTP client are fully runtime-agnostic. The subprocess transport (`subprocessConnect`) requires Bun.
|
|
36
|
+
|
|
37
|
+
### Browser Usage
|
|
38
|
+
|
|
39
|
+
The HTTP client works in browsers. Use `httpConnect` to call a `vgi-rpc` server from any browser application:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import { httpConnect } from "@query-farm/vgi-rpc";
|
|
43
|
+
|
|
44
|
+
const client = httpConnect("https://api.example.com");
|
|
45
|
+
const result = await client.call("add", { a: 2, b: 3 });
|
|
28
46
|
```
|
|
29
47
|
|
|
30
|
-
|
|
48
|
+
You will need a bundler (Vite, esbuild, webpack, etc.) that can resolve the `apache-arrow` dependency. Server-only exports (`VgiRpcServer`, `createHttpHandler`, `subprocessConnect`, `pipeConnect`) are not available in browsers.
|
|
31
49
|
|
|
32
50
|
## Quick Start
|
|
33
51
|
|
|
@@ -301,7 +319,7 @@ vgi-rpc --cmd "bun run examples/streaming.ts" call scale factor=2.0
|
|
|
301
319
|
|
|
302
320
|
## Wire Protocol Compatibility
|
|
303
321
|
|
|
304
|
-
This library implements the same wire protocol as the Python [vgi-rpc](https://github.com/Query-farm/vgi-rpc-python) framework:
|
|
322
|
+
This library implements the same wire protocol as the Python [`vgi-rpc`](https://github.com/Query-farm/vgi-rpc-python) framework:
|
|
305
323
|
|
|
306
324
|
- Multiple sequential Arrow IPC streams on stdin/stdout
|
|
307
325
|
- Request batches carry method name and version in batch metadata
|