@yorun-ai/vrpc 0.9.1 → 0.9.3

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/CONTRIBUTING.md CHANGED
@@ -5,7 +5,7 @@ This guide defines the development, verification, documentation, commit, and pul
5
5
  ## Prerequisites
6
6
 
7
7
  - Node.js 24.11 or later.
8
- - pnpm 11.15.0, using the repository lockfile.
8
+ - pnpm 12.5.1, using the repository lockfile.
9
9
 
10
10
  Install dependencies from the repository root:
11
11
 
@@ -22,6 +22,7 @@ pnpm install --frozen-lockfile
22
22
  - `src/entrypoints/`: public package entrypoints.
23
23
  - `test/`: behavioral, compatibility, and release tests.
24
24
  - `docs/guides/`: user-facing guides.
25
+ - `docs/reference/`: public API reference.
25
26
  - `docs/maintainers/`: architecture, protocol, and release documentation.
26
27
 
27
28
  Read `AGENTS.md`, `README.md`, and the applicable documentation before changing behavior or public contracts.
@@ -58,13 +59,34 @@ Do not commit generated `dist/` output or `node_modules/`.
58
59
 
59
60
  ## Documentation
60
61
 
61
- Repository documentation is maintained in English. The root `README.zh-CN.md` provides a Chinese project overview and links to the canonical English guides. Keep both root README files synchronized when their shared content changes.
62
+ Documentation is part of the public API contract. Repository documentation is
63
+ maintained in English; the root `README.zh-CN.md` is the Chinese entry point and
64
+ must stay structurally aligned with `README.md`. Keep both root README files
65
+ synchronized when their shared content changes.
62
66
 
63
67
  - Keep package overview and documentation navigation in `README.md` and `README.zh-CN.md`.
64
68
  - Put task-oriented material for package users in `docs/guides/`.
69
+ - Put public exports, option tables, defaults, and error fields in `docs/reference/`.
65
70
  - Put architecture, protocol, release, and other repository-maintenance material in `docs/maintainers/`.
66
71
  - Keep protocol details in `docs/maintainers/protocol.md` instead of duplicating them in the architecture overview.
67
72
 
73
+ Prefer linking to a canonical guide over duplicating long explanations across
74
+ the README and `docs/`. Do not shorten the README by deleting useful detail;
75
+ move that detail to the document that owns it.
76
+
77
+ ### Documentation requirements
78
+
79
+ When changing public exports, types, defaults, request behavior, headers, error
80
+ handling, or transport behavior:
81
+
82
+ - Update the relevant user guide.
83
+ - Update `docs/reference/README.md` when public signatures or behavior change.
84
+ - Update `docs/maintainers/protocol.md` when wire behavior changes.
85
+ - Keep README examples valid and consistent with the published package.
86
+ - Keep `README.md` and `README.zh-CN.md` structurally aligned.
87
+ - Verify CDN examples in `docs/guides/cdn.md` against the actual published
88
+ bundles, including loading mode and version pinning.
89
+
68
90
  ## Commits
69
91
 
70
92
  Create focused commits that explain the purpose of the change. Avoid mixing unrelated cleanup with functional work. Before committing, inspect the diff and run `git diff --check` in addition to the applicable project checks.
package/README.md CHANGED
@@ -1,14 +1,42 @@
1
1
  # @yorun-ai/vrpc
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/%40yorun-ai%2Fvrpc?label=version&logo=npm&style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
4
+ [![CI](https://img.shields.io/github/actions/workflow/status/yorun-ai/vrpc-ts/ci.yml?branch=main&label=CI&logo=github&style=flat-square)](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
5
+ [![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=%40yorun-ai%2Fvrpc&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.com/result?p=%40yorun-ai%2Fvrpc)
6
+ [![npm downloads](https://img.shields.io/npm/dm/%40yorun-ai%2Fvrpc?logo=npm&style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
7
+ [![npm types](https://img.shields.io/npm/types/%40yorun-ai%2Fvrpc?style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
8
+ [![license](https://img.shields.io/github/license/yorun-ai/vrpc-ts?style=flat-square)](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
9
+
3
10
  **English** | [简体中文](README.zh-CN.md)
4
11
 
5
- Client runtime for Vine vRPC and generic HTTP requests.
12
+ A lightweight TypeScript client runtime for [Vine](https://github.com/yorun-ai/vine) vRPC and generic HTTP requests.
6
13
 
7
- Repository: [github.com/yorun-ai/vrpc-ts](https://github.com/yorun-ai/vrpc-ts)
14
+ ## What is this?
8
15
 
9
- ## Stability
16
+ The package exposes two clients that share one request runtime:
17
+
18
+ - **vRPC client** — calls Vine vRPC methods over HTTP. It builds the vRPC path
19
+ and envelope, generates `vrpc-trace`, `vrpc-client`, and `vrpc-options`
20
+ headers, negotiates JSON or CBOR, and normalizes the vRPC response.
21
+ - **Generic HTTP client** — calls ordinary HTTP APIs with shared configuration,
22
+ interceptors, timeouts, cancellation, and normalized errors. It knows nothing
23
+ about the vRPC protocol.
10
24
 
11
- The package starts at `0.9.0`. It is ready for use, but versions below `1.0.0` do not guarantee a stable public API. Breaking API changes may be released in a new `0.x` minor version and will include migration guidance. Version `1.0.0` will mark the stable API commitment.
25
+ Choose the vRPC client when your server is a Vine vRPC service. Choose the
26
+ generic HTTP client for everything else. Both are Fetch-based and browser-first,
27
+ and both run in any JavaScript runtime that provides `fetch`.
28
+
29
+ ## Features
30
+
31
+ - TypeScript-first API with published types for every entry point.
32
+ - Browser Fetch-based transport, replaceable with a custom transport.
33
+ - Two clients: Vine vRPC and generic HTTP.
34
+ - Client-level defaults with per-request overrides.
35
+ - Interceptors for request, response, and error lifecycle hooks.
36
+ - Normalized, classified errors and `AbortSignal` cancellation.
37
+ - Optional CBOR integration through a user-provided codec, with no bundled
38
+ codec dependency.
39
+ - ESM and CommonJS builds, plus browser ES module CDN usage.
12
40
 
13
41
  ## Installation
14
42
 
@@ -16,20 +44,19 @@ The package starts at `0.9.0`. It is ready for use, but versions below `1.0.0` d
16
44
  pnpm add @yorun-ai/vrpc
17
45
  ```
18
46
 
19
- ## Entry points
47
+ ```bash
48
+ npm install @yorun-ai/vrpc
49
+ ```
20
50
 
21
- - `@yorun-ai/vrpc` / `@yorun-ai/vrpc/client`: vRPC client, protocol helpers, shared transport, and types.
22
- - `@yorun-ai/vrpc/http`: generic HTTP client.
51
+ ## Quick start
23
52
 
24
- ## vRPC quick start
53
+ ### 1. Invoke a vRPC method
25
54
 
26
55
  ```ts
27
- import { VrpcInvokeError, createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
56
+ import { createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
28
57
 
29
58
  const client = createVrpcClient({
30
59
  prefixUrl: "https://api.example.com/invoke",
31
- timeoutMs: 15_000,
32
- suppressGlobalToast: false,
33
60
  clientInfo: {
34
61
  clientName: "demo.browser",
35
62
  clientVersion: "1.0.0",
@@ -37,129 +64,17 @@ const client = createVrpcClient({
37
64
  },
38
65
  });
39
66
 
40
- client.use({
41
- onError(error, context) {
42
- if (context.options.suppressGlobalToast) {
43
- return;
44
- }
45
- console.error(error);
46
- },
47
- });
48
-
49
67
  const profile = await client.invoke<{ id: number; name: string }>({
50
68
  serviceName: "user.UserService",
51
69
  methodName: "getProfile",
52
70
  params: { userId: 1 },
53
- options: {
54
- timeoutMs: 3_000,
55
- suppressGlobalToast: true,
56
- },
57
- });
58
-
59
- // An argument-free method accepts null or an empty object.
60
- await client.invoke({
61
- serviceName: "user.UserService",
62
- methodName: "ping",
63
- params: null,
64
71
  });
65
-
66
- try {
67
- await client.invoke({
68
- serviceName: "user.UserService",
69
- methodName: "missing",
70
- params: {},
71
- });
72
- } catch (error) {
73
- if (error instanceof VrpcInvokeError) {
74
- console.error(error.status, error.vrpcStatus, error.code, error.reason);
75
- }
76
- }
77
72
  ```
78
73
 
79
- `traceMode` controls only the automatically generated `vrpc-trace` header; it does not change routing or `prefixUrl`. Use the default `"portal"` mode through Vine Portal, where the header contains only an id. For a direct connection to a vRPC service, set `traceMode: "direct"` so the runtime generates both an id and a span. Per-call `options.trace` overrides the generated value.
74
+ The final URL is `<prefixUrl>/<serviceName>/<methodName>`. Methods without
75
+ arguments accept `params: null` or `params: {}`.
80
76
 
81
- ### Request options
82
-
83
- ```ts
84
- type VrpcRequestOptions = {
85
- headers?: HeadersInit;
86
- timeoutMs?: number;
87
- requestInit?: Omit<RequestInit, "method" | "body" | "headers">;
88
- suppressGlobalToast?: boolean;
89
- trace?: { id: string; span?: string };
90
- wire?: VrpcMethodWireSpec;
91
- };
92
- ```
93
-
94
- - Create-time `suppressGlobalToast` is the default; a per-call `true` or `false` overrides it.
95
- - `timeoutMs` is disabled by default; without it, the built-in transport creates no local timeout and sends no `vrpc-options`.
96
- - `wire` is per-call only and never enters the HTTP payload.
97
- - Argument-free methods accept both `params: null` and `params: {}`.
98
- - The browser transport defaults to `credentials: "omit"`; use `requestInit.credentials` when cookies are needed.
99
-
100
- ## Automatic CBOR
101
-
102
- The runtime has no built-in CBOR dependency. A method without `wire` always uses JSON and requires no codec. Generated clients attach a sparse wire schema when a method's arguments or result contain Binary:
103
-
104
- ```ts
105
- import type { VrpcCborCodec, VrpcWireSchema } from "@yorun-ai/vrpc";
106
-
107
- const uploadArguments: VrpcWireSchema = {
108
- kind: "object",
109
- fields: {
110
- content: { kind: "binary" },
111
- },
112
- };
113
-
114
- const cborCodec: VrpcCborCodec = {
115
- encode: (value) => yourCborLibrary.encode(value),
116
- decode: (bytes) => yourCborLibrary.decode(bytes),
117
- };
118
-
119
- const client = createVrpcClient({
120
- prefixUrl: "https://api.example.com/invoke",
121
- clientInfo: {
122
- clientName: "demo.browser",
123
- clientVersion: "1.0.0",
124
- clientInstanceId: getClientInstanceId(),
125
- },
126
- cborCodec,
127
- });
128
-
129
- await client.invoke({
130
- serviceName: "file.FileService",
131
- methodName: "upload",
132
- params: { content: new Uint8Array([1, 2, 3]) },
133
- options: {
134
- wire: { arguments: uploadArguments },
135
- },
136
- });
137
- ```
138
-
139
- Automatic selection:
140
-
141
- - `wire.arguments`: the request `content-type` is `application/vrpc+cbor`.
142
- - `wire.result`: `accept` is `application/vrpc+cbor, application/vrpc+json`.
143
- - Neither: JSON.
144
- - Wire without `cborCodec` throws a configuration error before network I/O.
145
-
146
- `VrpcWireSchema` supports Binary, nullable, list, object, and `Map<Int|string, T>`. Binary remains raw bytes in CBOR, while an integer-keyed `Record` becomes a real integer-keyed CBOR Map.
147
-
148
- ## Vine Header
149
-
150
- Generated by the runtime:
151
-
152
- ```text
153
- content-type: application/vrpc+json
154
- accept: application/vrpc+json
155
- vrpc-trace: id=<32hex>
156
- vrpc-client: name=demo.browser,version=1.0.0,instanceId=<uuid>
157
- vrpc-options: timeout=3000ms
158
- ```
159
-
160
- Custom `headers` cannot override `accept`, `content-type`, or any `vrpc-*` header. An explicit `timeoutMs` controls both the local `AbortController` and `vrpc-options`.
161
-
162
- ## Generic HTTP client
77
+ ### 2. Call a plain HTTP API
163
78
 
164
79
  ```ts
165
80
  import { createHttpClient } from "@yorun-ai/vrpc/http";
@@ -169,14 +84,7 @@ const http = createHttpClient({
169
84
  timeoutMs: 5_000,
170
85
  });
171
86
 
172
- const profile = await http.request<{ id: number }>({
173
- path: "/users/me",
174
- query: { withProfile: true },
175
- options: {
176
- requestInit: { credentials: "include" },
177
- suppressGlobalToast: true,
178
- },
179
- });
87
+ const profile = await http.request<{ id: number }>({ path: "/users/me" });
180
88
 
181
89
  await http.request({
182
90
  path: "/users",
@@ -185,47 +93,123 @@ await http.request({
185
93
  });
186
94
  ```
187
95
 
188
- HTTP interceptors read merged request configuration from `context.options`. `json` and `body` are mutually exclusive, and an empty response returns `null`.
96
+ Use `json` for a JSON body and `body` for raw `BodyInit` values such as
97
+ `FormData`.
189
98
 
190
- ## Protocol helpers
99
+ ### 3. Handle errors
191
100
 
192
101
  ```ts
193
- import {
194
- buildVrpcHeaders,
195
- buildVrpcPath,
196
- buildVrpcRequestBody,
197
- generateVrpcId,
198
- } from "@yorun-ai/vrpc";
199
-
200
- const headers = buildVrpcHeaders({
201
- clientInfo: {
202
- clientName: "demo.browser",
203
- clientVersion: "1.0.0",
204
- clientInstanceId: getClientInstanceId(),
205
- },
206
- trace: { id: generateVrpcId() },
207
- timeoutMs: 3_000,
208
- });
102
+ import { isVrpcError } from "@yorun-ai/vrpc";
209
103
 
210
- const path = buildVrpcPath("user.UserService", "getProfile");
211
- const body = buildVrpcRequestBody({ userId: 1 });
104
+ try {
105
+ await client.invoke({
106
+ serviceName: "user.UserService",
107
+ methodName: "getProfile",
108
+ params: { userId: 1 },
109
+ });
110
+ } catch (error) {
111
+ if (isVrpcError(error) && error.kind === "invoke") {
112
+ // Server rejected the invocation.
113
+ console.error(error.vrpcStatus, error.code, error.reason);
114
+ }
115
+ }
212
116
  ```
213
117
 
118
+ The generic HTTP client provides the equivalent `isHttpError` guard.
119
+
120
+ ## Browser CDN
121
+
122
+ Use the published ES module builds when you want to try a client without
123
+ installing a package or configuring a bundler:
124
+
125
+ ```html
126
+ <script type="module">
127
+ import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
128
+
129
+ // ...
130
+ </script>
131
+ ```
132
+
133
+ The package ships ES modules only. There is no global build, so a classic
134
+ `<script src="...">` tag cannot be used; the tag must have `type="module"`.
135
+
136
+ See [Browser CDN usage](docs/guides/cdn.md) for complete HTML examples, the
137
+ generic HTTP entry, version pinning, and troubleshooting.
138
+
139
+ ## Entry points
140
+
141
+ | Import | Contents |
142
+ | ----------------------- | ------------------------------------------------------------- |
143
+ | `@yorun-ai/vrpc` | vRPC client, protocol helpers, transport, errors, and types. |
144
+ | `@yorun-ai/vrpc/client` | Explicit vRPC entry; identical to the package root. |
145
+ | `@yorun-ai/vrpc/http` | Generic HTTP client, Fetch transport, HTTP errors, and types. |
146
+
147
+ ## Configuration at a glance
148
+
149
+ Both clients accept `prefixUrl`, `headers`, `timeoutMs`, `requestInit`,
150
+ `suppressGlobalToast`, `fetchImpl`, `transport`, and `interceptors`. The vRPC
151
+ client additionally requires `clientInfo` and accepts `traceMode` and
152
+ `cborCodec`. Per-request `options` override client defaults, and
153
+ `context.options` always contains the merged result.
154
+
155
+ The vRPC client adds two request options: `trace` replaces the generated
156
+ `vrpc-trace` header, and `wire` selects JSON or CBOR for a single call. A wire
157
+ schema is never serialized into the HTTP body, and it requires a `cborCodec`.
158
+
159
+ ## Advanced capabilities
160
+
161
+ - **Interceptors** — `beforeRequest`, `afterResponse`, and `onError` hooks
162
+ registered with `client.use()`. `onError` runs before the request promise
163
+ rejects and does not swallow the failure.
164
+ - **Cancellation** — pass an `AbortSignal` through `requestInit.signal`.
165
+ Cancellation rejects with `kind: "abort"`. Timeouts stay `kind: "timeout"`.
166
+ - **Tracing** — `traceMode: "portal"` (default) generates a trace id;
167
+ `traceMode: "direct"` also generates a span. It never changes routing or
168
+ `prefixUrl`.
169
+ - **CBOR** — provide a `cborCodec` and a per-call `wire` schema when arguments
170
+ or results contain `Binary`.
171
+ - **Custom transport** — implement `VrpcTransport` or `HttpTransport` to
172
+ replace Fetch with another I/O layer.
173
+ - **`suppressGlobalToast`** — application-defined error UI policy metadata.
174
+ The package never displays UI, skips `onError`, or consumes the rejection.
175
+
176
+ The [Usage guide](docs/guides/usage.md) covers each capability with runnable
177
+ examples.
178
+
214
179
  ## Documentation
215
180
 
216
- User guides:
181
+ ### User guides
182
+
183
+ - [Usage](docs/guides/usage.md) — client configuration, request options,
184
+ interceptors, errors, cancellation, CBOR, and custom transports.
185
+ - [Browser CDN](docs/guides/cdn.md) — CDN loading modes and complete HTML
186
+ examples.
187
+ - [Axios integration](docs/guides/axios.md) — custom Axios transport and JSON
188
+ protocol helpers.
217
189
 
218
- - [Usage](./docs/guides/usage.md): HTTP/vRPC client configuration and extension points.
219
- - [Axios integration](./docs/guides/axios.md): custom Axios transport and JSON protocol helpers.
190
+ ### Reference and maintainers
220
191
 
221
- Maintainer documentation:
192
+ - [API Reference](docs/reference/README.md) — public exports, types,
193
+ configuration options, defaults, and errors.
194
+ - [Architecture](docs/maintainers/architecture.md) — module boundaries and
195
+ request flow.
196
+ - [vRPC protocol](docs/maintainers/protocol.md) — paths, envelopes, headers,
197
+ content negotiation, wire schemas, and generated-client requirements.
198
+ - [Releasing](docs/maintainers/releasing.md) — version management and npm
199
+ publishing.
200
+ - [Contributing](CONTRIBUTING.md) — development, testing, documentation, and
201
+ pull-request workflow.
222
202
 
223
- - [Architecture](./docs/maintainers/architecture.md): module boundaries and request flow.
224
- - [vRPC protocol](./docs/maintainers/protocol.md): paths, envelopes, headers, content negotiation, wire schemas, and generated-client requirements.
225
- - [Releasing](./docs/maintainers/releasing.md): version management and npm publishing.
226
- - [Contributing](./CONTRIBUTING.md): development, testing, documentation, commit, and pull-request workflow.
203
+ The root README and `docs/guides/` are for package users. `docs/maintainers/`
204
+ is for repository maintainers and integrators implementing transports or code
205
+ generation.
206
+
207
+ ## Stability
227
208
 
228
- The root README and `docs/guides/` are for package users. `docs/maintainers/` is for repository maintainers and integrators implementing transports or code generation. Changes to public exports, types, defaults, headers, errors, or request behavior must be reflected in both the user-facing and maintainer documentation.
209
+ The package is in the `0.x` release line. It is ready for use, but versions
210
+ below `1.0.0` do not guarantee a stable public API. A breaking change may be
211
+ released in a new `0.x` minor version and will include migration guidance.
212
+ Version `1.0.0` will mark the stable API commitment.
229
213
 
230
214
  ## License
231
215