Skip to content

Commit badb514

Browse files
emrulemrul
committed
docs(bindings/typescript,api): sweep TS binding pages + publish API references
TypeScript binding pages (docs/bindings/javascript/): - Quick example in index.mdx no longer uses LocalTransport+ServiceRegistry for the "first 30 seconds" path. That's a testing-only API; the canonical pattern is `new AsterServer({ services })` + `new AsterClientWrapper({ address }).proxy("Name")`, matching the Python equivalent in bindings/python/index.mdx and the Mission Control guide. Producer and consumer are now in two clearly-labelled blocks. - server.mdx: `endpointAddr` -> `address` (the canonical property name); added the missing `await server.serve()` call that actually blocks the process; expanded the Options table to include identity/peer/ allowAllConsumers; method decorators now show `request:` / `response:` explicit constructors with a callout explaining why TypeScript needs them (runtime type erasure breaks the gen-client manifest otherwise). - client.mdx: AsterClientWrapper is now the primary section -- it's the thing users actually call; createClient is described as a lower-level helper for tests. Removed a confusing `myTransport` example that conflicted with the rest of the page. Python API reference (static/api/python/): - Regenerated from the freshly-updated `aster.public` curated module. Now includes AdmissionDeniedError, ContractViolationError, SerializationMode, and the full interceptor surface that shipped in aster-rpc 0.1.2 but was missing from the previous build. TypeScript API reference (static/api/typescript/): - New, generated by TypeDoc from the new `@aster-rpc/aster/src/public.ts` curated entry point. Mirrors the Python API reference structure -- same surface area, same focus on user-facing types only. - Both reference sites are now regenerated by `./scripts/build-api-docs.sh` in the framework repo.
1 parent d4856a6 commit badb514

72 files changed

Lines changed: 8521 additions & 4028 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/bindings/javascript/client.mdx‎

Lines changed: 50 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,63 @@ slug: /bindings/typescript/client
66

77
# TypeScript Client Reference
88

9-
## createClient
9+
## AsterClientWrapper
1010

11-
The primary way to create a typed RPC client. Uses JavaScript `Proxy` for method interception with full TypeScript type inference.
11+
The primary way to connect to an Aster server over QUIC. Handles consumer admission, service discovery, and the proxy/typed-client surface.
1212

1313
```typescript
14-
import { createClient, LocalTransport, ServiceRegistry } from '@aster-rpc/aster';
15-
import { HelloService } from './service.js';
16-
import { HelloRequest } from './types.js';
14+
import { AsterClientWrapper } from '@aster-rpc/aster';
1715

18-
const registry = new ServiceRegistry();
19-
registry.register(new HelloService());
20-
const transport = new LocalTransport(registry);
16+
const client = new AsterClientWrapper({
17+
address: "aster1...",
18+
});
19+
await client.connect();
2120

22-
const client = createClient(HelloService, transport);
21+
// Dynamic proxy: speaks JSON, no local types needed
22+
const hello = client.proxy("Hello");
23+
const reply = await hello.sayHello({ name: "World" });
24+
console.log(reply.message);
25+
26+
await client.close();
27+
```
28+
29+
### Options
30+
31+
| Option | Type | Default | Description |
32+
|--------|------|---------|-------------|
33+
| `address` | `string` | `undefined` | `aster1...` ticket of the producer to connect to |
34+
| `transport` | `AsterTransport` | `undefined` | Pre-built transport (for tests). Mutually exclusive with `address`. |
35+
| `config` | `Partial<AsterConfig>` | `{}` | Override config values |
36+
| `identity` | `string` | `undefined` | Path to a `.aster-identity` TOML file |
37+
| `peer` | `string` | `undefined` | Peer name to load from the identity file |
38+
| `enrollmentCredentialFile` | `string` | `undefined` | Path to a `.cred` enrollment credential for trusted-mode servers |
39+
40+
### Methods
41+
42+
| Method | Returns | Description |
43+
|--------|---------|-------------|
44+
| `connect()` | `Promise<void>` | Run consumer admission against the producer and discover services |
45+
| `proxy(name)` | `ProxyClient` | Dynamic proxy for a service. Speaks JSON; no codegen needed. |
46+
| `client(ServiceClass)` | `Promise<typed client>` | Typed client built from a generated client class |
47+
| `session(name)` | `Promise<SessionProxyClient>` | Open a multiplexed session against a session-scoped service |
48+
| `close()` | `Promise<void>` | Close the underlying QUIC connections |
49+
50+
### Properties
51+
52+
| Property | Type | Description |
53+
|----------|------|-------------|
54+
| `connected` | `boolean` | Whether `connect()` has succeeded |
55+
| `services` | `ServiceSummary[]` | Services discovered during admission |
56+
57+
## Lower-level: createClient
2358

24-
// Full type inference — client.sayHello() has correct parameter and return types
59+
For tests and advanced use, `createClient` builds a typed stub over an existing transport. This is what `AsterClientWrapper.client()` uses internally.
60+
61+
```typescript
62+
import { createClient } from '@aster-rpc/aster';
63+
64+
const client = createClient(HelloService, transport);
2565
const result = await client.sayHello(new HelloRequest({ name: "World" }));
26-
console.log(result.message); // "Hello, World!"
2766
```
2867

2968
### Signature
@@ -96,24 +135,6 @@ for await (const reply of channel) {
96135
}
97136
```
98137

99-
## AsterClientWrapper
100-
101-
The high-level client wrapper for production use:
102-
103-
```typescript
104-
import { AsterClientWrapper } from '@aster-rpc/aster';
105-
106-
const client = new AsterClientWrapper({
107-
transport: myTransport,
108-
config: { logFormat: 'json' },
109-
});
110-
111-
const echo = client.service(HelloService);
112-
const result = await echo.sayHello(new HelloRequest({ name: "World" }));
113-
114-
await client.close();
115-
```
116-
117138
## Transport implementations
118139

119140
| Transport | Use case | Package |

‎docs/bindings/javascript/index.mdx‎

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -35,41 +35,57 @@ The `@aster-rpc/transport` native addon is included as a dependency and auto-sel
3535

3636
## Quick example
3737

38+
A producer hosts a service over QUIC; a consumer connects by address.
39+
3840
```typescript
39-
import { Service, Rpc, WireType, AsterServer, createClient, LocalTransport, ServiceRegistry } from '@aster-rpc/aster';
41+
// service.ts
42+
import { Service, Rpc, AsterServer, AsterClientWrapper } from '@aster-rpc/aster';
4043

41-
// Define wire types
42-
@WireType("hello/HelloRequest")
4344
class HelloRequest {
4445
name = "";
4546
constructor(init?: Partial<HelloRequest>) { if (init) Object.assign(this, init); }
4647
}
4748

48-
@WireType("hello/HelloResponse")
4949
class HelloResponse {
5050
message = "";
5151
constructor(init?: Partial<HelloResponse>) { if (init) Object.assign(this, init); }
5252
}
5353

54-
// Define service
5554
@Service({ name: "Hello", version: 1 })
56-
class HelloService {
57-
@Rpc()
55+
export class HelloService {
56+
@Rpc({ request: HelloRequest, response: HelloResponse })
5857
async sayHello(req: HelloRequest): Promise<HelloResponse> {
5958
return new HelloResponse({ message: `Hello, ${req.name}!` });
6059
}
6160
}
6261

63-
// Create and call
64-
const registry = new ServiceRegistry();
65-
registry.register(new HelloService());
66-
const transport = new LocalTransport(registry);
62+
// Producer
63+
const server = new AsterServer({ services: [new HelloService()] });
64+
await server.start();
65+
console.log("Producer ready at:", server.address);
66+
await server.serve();
67+
```
68+
69+
```typescript
70+
// consumer.ts
71+
import { AsterClientWrapper } from '@aster-rpc/aster';
6772

68-
const client = createClient(HelloService, transport);
69-
const result = await client.sayHello(new HelloRequest({ name: "TypeScript" }));
70-
console.log(result.message); // "Hello, TypeScript!"
73+
const client = new AsterClientWrapper({
74+
address: process.env.ASTER_ENDPOINT_ADDR!,
75+
});
76+
await client.connect();
77+
78+
// The dynamic proxy speaks JSON and needs no local type definitions --
79+
// methods are discovered from the producer's published contract.
80+
const hello = client.proxy("Hello");
81+
const reply = await hello.sayHello({ name: "TypeScript" });
82+
console.log(reply.message); // "Hello, TypeScript!"
83+
84+
await client.close();
7185
```
7286

87+
For full type safety on the consumer side, generate a typed client with `aster contract gen-client <address> --lang typescript --out ./clients` and import it instead of using `client.proxy()`.
88+
7389
## Architecture
7490

7591
```

‎docs/bindings/javascript/server.mdx‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ import { HelloService } from './service.js';
1717
const server = new AsterServer({
1818
services: [new HelloService()],
1919
config: {
20-
healthPort: 8080,
2120
logFormat: 'json',
2221
},
2322
});
2423

2524
await server.start();
26-
console.log("Server started");
25+
console.log("Producer ready at:", server.address);
26+
await server.serve(); // blocks until shutdown
2727
```
2828

2929
### Options
@@ -32,21 +32,25 @@ console.log("Server started");
3232
|--------|------|---------|-------------|
3333
| `services` | `object[]` | Required | Array of `@Service`-decorated instances |
3434
| `config` | `Partial<AsterConfig>` | `{}` | Override config values |
35+
| `identity` | `string` | `undefined` | Path to a `.aster-identity` TOML file |
36+
| `peer` | `string` | `undefined` | Peer name to load from the identity file |
37+
| `allowAllConsumers` | `boolean` | `true` | Open-gate mode (dev). Set `false` for trusted mode. |
3538
| `interceptors` | `Interceptor[]` | `[]` | Server-side interceptors |
3639

3740
### Methods
3841

3942
| Method | Returns | Description |
4043
|--------|---------|-------------|
41-
| `start()` | `Promise<void>` | Start the server (create node, publish contracts, start health) |
44+
| `start()` | `Promise<void>` | Start the server (create node, publish contracts, open admission) |
45+
| `serve()` | `Promise<void>` | Block until the server is shut down (Ctrl+C in scripts) |
4246
| `close()` | `Promise<void>` | Graceful shutdown |
4347
| `localTransport()` | `LocalTransport` | In-process transport for testing |
4448

4549
### Properties
4650

4751
| Property | Type | Description |
4852
|----------|------|-------------|
49-
| `endpointAddr` | `string \| undefined` | Base64 NodeAddr for clients |
53+
| `address` | `string` | `aster1...` ticket consumers connect to |
5054
| `running` | `boolean` | Whether the server is running |
5155
| `registry` | `ServiceRegistry` | The service registry |
5256
| `config` | `AsterConfig` | Resolved configuration |
@@ -85,28 +89,36 @@ class EchoService { ... }
8589
### @Rpc
8690

8791
```typescript
88-
@Rpc({ timeout: 30, idempotent: true })
92+
@Rpc({ request: EchoRequest, response: EchoResponse, timeout: 30, idempotent: true })
8993
async echo(req: EchoRequest): Promise<EchoResponse> { ... }
9094
```
9195

96+
> **Note:** TypeScript erases generic type parameters at runtime, so the
97+
> contract publisher and the `gen-client` codegen pipeline cannot discover
98+
> the request and response shapes from the method signature alone. Pass
99+
> the constructors explicitly via `request:` and `response:` so the
100+
> published manifest carries the wire tag and field list -- this is
101+
> required for cross-language consumers (Python, Go, Java) to talk to
102+
> the service.
103+
92104
### @ServerStream
93105

94106
```typescript
95-
@ServerStream()
107+
@ServerStream({ request: WatchRequest, response: ItemUpdate })
96108
async *watchItems(req: WatchRequest): AsyncGenerator<ItemUpdate> { ... }
97109
```
98110

99111
### @ClientStream
100112

101113
```typescript
102-
@ClientStream()
114+
@ClientStream({ request: Item, response: BatchResult })
103115
async uploadBatch(requests: AsyncIterable<Item>): Promise<BatchResult> { ... }
104116
```
105117

106118
### @BidiStream
107119

108120
```typescript
109-
@BidiStream()
121+
@BidiStream({ request: Message, response: Message })
110122
async *chat(requests: AsyncIterable<Message>): AsyncGenerator<Message> { ... }
111123
```
112124

0 commit comments

Comments
 (0)