PicoRPC

A tiny RPC library and spec, inspired by JSON-RPC 2.0 and tRPC.

Install

1npm install --save picorpc

Usage

1import {createAbstractClient, createAbstractServer} from 'picorpc';
2import {createMemoryClient, createMemoryServer} from 'picorpc';
3import {createHttpClient, createHttpServer} from 'picorpc';
4
5// Custom map of procedures to expose to the client
6
7const Procedures = {
8  ctx () { // This procedure reads something from the context, which will be attached to "this"
9    return this.value;
10  },
11  sum ( a, b ) { // This procedure is a simple pure function that doesn't use the context
12    return a + b;
13  },
14  throw () { // This procedure throws, with a custom error code and data value
15    const error = new Error ( 'Some custom error' );
16    error.code = 1;
17    error.data = 'Some data';
18    throw error;
19  }
20};
21
22// Create an in-memory client/server
23// An in-memory server behind a proper HTTP server is the recommended way to expose procedures via an API
24// An in-memory client is mostly useful for testing
25
26const server = createMemoryServer ({
27  procedures: Procedures
28});
29
30const client = createMemoryClient ({
31  server, // The in-memory server to pass requests to
32  context: () => ({ // Custom, optional, context object, which will be attached to every request automatically
33    value: 123
34  })
35});
36
37await client.sum ( 1, 2 ); // => 3
38await client.ctx (); // => 123
39await client.throw (); // => This will throw
40
41// Create an HTTP client/server
42// The HTTP server is intended for simple internal inter-process communication
43// The HTTP client makes request with the fetch API, so it works everywhere
44
45const client = createHttpClient ({
46  context: () => ({ // Custom, optional, context object, which will be attached to every request automatically
47    value: 123
48  }),
49  serializer: JSON.stringify, // Custom, optional, serializer
50  deserializer: JSON.parse, // Custom, optional, deserializer
51  url: 'http://localhost:6000' // Required endpoint URL
52});
53
54const server = createHttpServer ({
55  serializer: JSON.stringify, // Custom, optional, serializer
56  deserializer: JSON.parse, // Custom, optional, deserializer
57  port: 6000, // The port to start listening at
58  procedures: Procedures
59});
60
61await client.sum ( 1, 2 ); // => 3
62await client.ctx (); // => 123
63await client.throw (); // => This will throw
64
65server.close (); // Close the server, stopping listening
66
67// Create an abstract server, to use your own transport protocol
68
69const client = createAbstractClient ({
70  handler: request => {
71    //TODO: Send the request somewhere and read the result back
72  }
73});
74
75const client = createAbstractServer ({
76  procedures: Procedures,
77  handler: response => {
78    //TODO: Do something with the response object, optionally
79  }
80});

License

MIT © Fabio Spampinato