better-grpc 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+![Banner](./.github/assets/banner.png)
+
 # better-grpc
 
 > Simple, typed gRPC for TypeScript
@@ -38,7 +40,7 @@ yarn add better-grpc
 Create an abstract class that extends `Service` to define your service. Use the `server` and `client` helpers to define where your function is implemented and executed.
 
 ```typescript
-import { Service, client, server } from 'better-grpc';
+import { Service, client, server, bidi } from 'better-grpc';
 
 abstract class MyService extends Service('MyService') {
     // This function is implemented and executed on the server.
@@ -46,6 +48,9 @@ abstract class MyService extends Service('MyService') {
 
     // This function is implemented and executed on the client.
     log = client<(message: string) => void>();
+
+    // This function supports bidirectional streaming between client and server.
+    chat = bidi<(message: string) => void>();
 }
 ```
 
@@ -104,6 +109,78 @@ await server.MyService.log('Greeting from server');
 // The client's console will show: '[Server]: Greeting from server'
 ```
 
+### 6. Use bidirectional streams
+
+Bidirectional gRPCs expose a function that both emits values (when you invoke it) and acts as an async iterator so you can consume the opposite side's messages.
+
+```typescript
+// Client usage
+await client.MyService.chat('hello from client'); // emit to the server
+
+for await (const [message] of client.MyService.chat) {
+    console.log('Server replied:', message);
+    break;
+}
+
+// Server usage mirrors the client
+await server.MyService.chat('hello from server'); // emit to the client
+
+for await (const [message] of server.MyService.chat) {
+    console.log('Client replied:', message);
+    break;
+}
+```
+
+### 7. Attach typed metadata
+
+Define metadata requirements with [Zod](https://github.com/colinhacks/zod) schemas, and `better-grpc` will automatically type the context on both sides and marshal the payload into gRPC metadata.
+
+```typescript
+import { Service, server, bidi } from 'better-grpc';
+import { z } from 'zod';
+
+abstract class GreeterService extends Service('GreeterService') {
+    greet = server<(name: string) => string>()({
+        metadata: z.object({ requestId: z.string() }),
+    });
+
+    chat = bidi<(message: string) => void>()({
+        metadata: z.object({ room: z.string() }),
+    });
+}
+```
+
+Server implementations receive the typed metadata as the first argument:
+
+```typescript
+const GreeterServerImpl = GreeterService.Server({
+    async greet(context, name) {
+        console.log('Request', context.metadata.requestId);
+        return `Hello, ${name}!`;
+    },
+});
+```
+
+On the client, unary calls that require metadata expose a `.withMeta()` helper, and bidi streams provide a `.context()` helper that must be awaited and called before sending messages (the bidi stream will be established after calling `.context()`):
+
+```typescript
+await client.GreeterService.greet('Ada').withMeta({ requestId: crypto.randomUUID() });
+
+await client.GreeterService.chat.context({
+    metadata: { room: 'general' },
+});
+// you must provide the context before calling the bidi function;
+// otherwise, it will continue to wait.
+await client.GreeterService.chat('hello from client');
+```
+
+On the server side, the bidi function expose a `.context` value that can be used to access metadata:
+
+```typescript
+const chatContext = await server.GreeterService.chat.context;
+console.log(chatContext.metadata.room); // 'general'
+````
+
 ## Why `better-grpc`?
 
 The traditional workflow for creating gRPC services with TypeScript involves writing `.proto` files, using `protoc` to generate TypeScript code, and then using that generated code. This process can be cumbersome and result in a disconnect between your service definition and your code.
@@ -123,11 +200,15 @@ A factory function that creates an abstract service class.
 
 - `server<T>()`
 
-A helper function to define a server-side function signature. `T` should be a function type.
+Defines a server-side unary function signature. `T` should be a function type. Call the returned descriptor with `({ metadata: z.object({...}) })` to require typed metadata for that RPC. Client code then calls `client.MyService.fn(...args).withMeta({...})`, and server handlers receive the context object as the first argument.
 
 - `client<T>()`
 
-A helper function to define a client-side function signature. `T` should be a function type.
+Defines a client-side unary function signature. `T` should be a function type.
+
+- `bidi<T>()`
+
+Defines a bidirectional stream signature. `T` should be a function type that returns `void`. Like `server()`, you can pass `({ metadata: schema })` to type the attached metadata; client stubs expose `bidiFn.context({ metadata })` and server stubs expose `await bidiFn.context` to read it.
 
 - `createGrpcServer(port: number, ...services: ServiceImpl[])`
 
@@ -164,4 +245,4 @@ better-grpc: 126.681042ms
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.