Skip to content

Commit 93dbb58

Browse files
committed
docs: Start split into per-language documentation, link library API in reference
1 parent f70d4f0 commit 93dbb58

1 file changed

Lines changed: 24 additions & 10 deletions

File tree

README.md

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,13 @@ It enables you to ...
3131

3232
### Library
3333

34-
You can add panrpc to your Go project by running the following:
34+
You can add panrpc to your **Go** project by running the following:
3535

3636
```shell
3737
go get github.com/pojntfx/panrpc/...@latest
3838
```
3939

40-
For TypeScript, you can add panrpc to your project (both server-side TypeScript/Node.js and all major browser engines are supported) by running the following:
40+
For **TypeScript**, you can add panrpc to your project (both server-side TypeScript/Node.js and all major browser engines are supported) by running the following:
4141

4242
```shell
4343
npm i -s @pojntfx/panrpc
@@ -71,9 +71,14 @@ You can find binaries for more operating systems and architectures on [GitHub re
7171

7272
## Usage
7373

74+
### Go
75+
76+
<details>
77+
<summary>Expand instructions</summary>
78+
7479
> TL;DR: Define the local and remote functions as struct methods, add them to a registry and link it with a transport
7580
76-
### 1. Define Local Functions
81+
#### 1. Define Local Functions
7782

7883
panrpc uses reflection to create the glue code required to expose and call functions. Start by defining your server's exposed functions like so:
7984

@@ -113,7 +118,7 @@ The following limitations on which functions you can expose exist:
113118
- Functions can not have variadic arguments
114119
- Functions must return either an error or a single value and an error
115120

116-
### 2. Define Remote Functions
121+
#### 2. Define Remote Functions
117122

118123
Next, define the functions exposed by the client to the server using a struct without method implementations:
119124

@@ -135,7 +140,7 @@ type remote struct {
135140
}
136141
```
137142

138-
### 3. Add Functions to a Registry
143+
#### 3. Add Functions to a Registry
139144

140145
For the server, you can now create the registry, which will expose its functions:
141146

@@ -167,7 +172,7 @@ registry := rpc.NewRegistry[remote, json.RawMessage](
167172

168173
Note the second generic parameter; it is the type that should be used for encoding nested messages. For JSON, this is typically `json.RawMessage`, for CBOR, this is `cbor.RawMessage`. Using such a nested message type is recommended, as it leads to a faster encoding/decoding since it doesn't require multiple encoding/decoding steps in order to function, but using `[]byte` (which will use multiple encoding/decoding steps) is also possible if this is not an option (for more infromation, see [Protocol](#protocol)).
169174

170-
### 4. Link the Registry to a Transport and Serializer
175+
#### 4. Link the Registry to a Transport and Serializer
171176

172177
Next, expose the functions by linking them to a transport. There are two available transport APIs; the [Stream-Oriented API](https://pkg.go.dev/github.com/pojntfx/panrpc/pkg/rpc#LinkStream) (which is useful for stream-like transports such as TCP, WebSockets, WebRTC or anything else that provides an `io.ReadWriteCloser`), and the [Message-Oriented API](https://pkg.go.dev/github.com/pojntfx/panrpc/pkg/rpc#LinkMessage) (which is useful for transports that use messages, such as message brokers like Redis, UDP or other packet-based protocols). In this example, we'll use the stream-oriented API; for more information on using the m, meaning it can run in the browser!essage-oriented API, see [Examples](#examples).
173178

@@ -268,7 +273,7 @@ if err := registry.LinkStream(
268273
}
269274
```
270275

271-
### 5. Call the Functions
276+
#### 5. Call the Functions
272277

273278
Now you can call the functions exposed on the server from the client and vise versa. For example, to call `Println`, a function exposed by the client from the server:
274279

@@ -336,7 +341,7 @@ registry := rpc.NewRegistry[remote, json.RawMessage](
336341
service.ForRemotes = registry.ForRemotes
337342
```
338343

339-
### 6. Using Closures and Callbacks
344+
#### 6. Using Closures and Callbacks
340345

341346
Because panrpc is bidirectional, it is possible to pass closures and callbacks as function arguments, just like you would locally. For example, on the server:
342347

@@ -402,10 +407,19 @@ if err := registry.ForRemotes(func(remoteID string, remote remote) error {
402407
}
403408
```
404409

405-
🚀 That's it! We can't wait to see what you're going to build with panrpc.
410+
🚀 That's it! We can't wait to see what you're going to build with panrpc. Be sure to take a look at the [reference](#reference) and [examples](#examples) for more information.
411+
412+
</details>
413+
414+
### TypeScript
406415

407416
## Reference
408417

418+
### Library API
419+
420+
- [![Go Reference](https://pkg.go.dev/badge/github.com/pojntfx/panrpc.svg)](https://pkg.go.dev/github.com/pojntfx/panrpc)
421+
- [![TypeScript docs](https://img.shields.io/badge/TypeScript%20-docs-blue.svg)](https://pojntfx.github.io/panrpc)
422+
409423
### Examples
410424

411425
To make getting started with panrpc easier, take a look at the following examples:
@@ -554,7 +568,7 @@ Here, `response` specifies that the message is a function return. `call` is the
554568

555569
Keep in mind that panrpc is bidirectional, meaning that both the client and server can send and receive both types of messages to each other.
556570

557-
## Reference
571+
### `purl` Command Line Arguments
558572

559573
```shell
560574
$ purl --help

0 commit comments

Comments
 (0)