@zmdb/transport-grpc 1.0.0-beta.1

package/README.md

@@ -0,0 +1,83 @@
+# @zmdb/transport-grpc
+
+`@zmdb/transport-grpc` binds generated `@zmdb/protobuf` service artifacts to real grpc-js servers and typed clients. It owns deadlines, cancellation, metadata validation, streaming and bounded
+application shutdown without parsing `.proto` files at runtime.
+
+## Install
+
+```bash
+yarn add @zmdb/app@1.0.0-beta.1 @zmdb/protobuf@1.0.0-beta.1 @zmdb/transport-grpc@1.0.0-beta.1 @grpc/grpc-js@^1.14.4
+yarn add @zmdb/validator@1.0.0-beta.1
+yarn add --dev @zmdb/compiler@1.0.0-beta.1
+```
+
+> **Prerelease** (`1.0.0-beta.1`). Requires **Node.js 26+** and is **ESM-only**. Ships built ESM `.js` + `.d.ts` under `./dist`.
+
+The sole peer is `@grpc/grpc-js@^1.14.4`. The package is not installed by `yarn add zmdb@1.0.0-beta.1`; `@zmdb/protobuf` supplies the source-level service artifact, `@zmdb/compiler` emits it at build
+time, and the generated validators import the `@zmdb/validator` runtime ABI.
+
+## Usage
+
+```ts
+import { Module, createApplication } from '@zmdb/app';
+import { loadGrpcService } from '@zmdb/protobuf';
+import { type ProtoField } from '@zmdb/schema/tags';
+import { bindGrpcService, grpcExtension, type GrpcMetadata } from '@zmdb/transport-grpc';
+
+interface GetOrder {
+  readonly id: string & ProtoField<1>;
+}
+
+interface Order {
+  readonly id: string & ProtoField<1>;
+}
+
+type Orders = {
+  readonly get: { readonly request: GetOrder; readonly response: Order };
+};
+
+const ordersService = loadGrpcService<Orders>('Orders', 'orders');
+
+const orders = bindGrpcService(
+  {
+    definition: ordersService,
+    validateMetadata: (metadata: GrpcMetadata) => metadata,
+    onError: failure => console.error(failure.error),
+  },
+  {
+    get: async call => ({ id: call.payload.id }),
+  },
+);
+
+@Module({})
+class AppModule {}
+
+await using app = createApplication(AppModule, {
+  extensions: [
+    grpcExtension({
+      address: '0.0.0.0:50051',
+      bindings: [orders],
+      credentials: 'insecure',
+    }),
+  ],
+});
+
+await app.init();
+```
+
+The caller owns every client returned by `createGrpcClient` and closes it with `close()` or `Symbol.dispose`. The application owns the server extension and applies its configured grace budget during
+shutdown. The extension owns its grpc-js server; it attempts graceful shutdown, then forces closure when the grace budget expires.
+
+## Entry points
+
+- `@zmdb/transport-grpc` — server bindings, `grpcExtension`, typed clients, status errors and application-facing gRPC types.
+
+## Documentation
+
+Typed gRPC guide: **https://ambasta.github.io/zmdb/docs/web-microservices-grpc.html**
+
+Full docs: **https://ambasta.github.io/zmdb/**
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later) — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { bindGrpcService, createGrpcClient, grpcExtension } from './runtime.js';
+export { GrpcError, type GrpcBinding, type GrpcCall, type GrpcCaller, type GrpcClient, type GrpcClientCallOptions, type GrpcClientOptions, type GrpcClientTlsOptions, type GrpcFailure, type GrpcHandler, type GrpcHandlers, type GrpcKeyCertPair, type GrpcMetadata, type GrpcMetadataValidator, type GrpcServerOptions, type GrpcServerTlsOptions, type GrpcServiceSpec, type GrpcStatus, type GrpcTlsOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EACL,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { bindGrpcService, createGrpcClient, grpcExtension } from './runtime.js';
+export { GrpcError, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EACL,SAAS,GAmBV,MAAM,YAAY,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { ApplicationExtension } from '@zmdb/app';
+import type { GrpcServiceDef } from '@zmdb/protobuf';
+import { type GrpcBinding, type GrpcClient, type GrpcClientOptions, type GrpcHandlers, type GrpcServerOptions, type GrpcServiceSpec } from './types.js';
+export interface OpenedGrpcServer {
+    readonly port: number;
+    close(graceMs: number): Promise<void>;
+}
+/** Bind one generated service definition to its exhaustive typed handler map. */
+export declare function bindGrpcService<S extends GrpcServiceDef>(service: GrpcServiceSpec<S>, handlers: GrpcHandlers<S>): GrpcBinding;
+/** Attach one gRPC server to the protocol-neutral application lifecycle. */
+export declare function grpcExtension(options: GrpcServerOptions): ApplicationExtension;
+/** Create a typed client from the same generated service artifact used by the server. */
+export declare function createGrpcClient<S extends GrpcServiceDef>(options: GrpcClientOptions<S>): GrpcClient<S>;
+/** Start all bound services. Kept internal to the application lifecycle. */
+export declare function openGrpcServer(options: GrpcServerOptions): Promise<OpenedGrpcServer>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEtF,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAEf,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAGjB,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAgFD,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,EACtD,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GACxB,WAAW,CAGb;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,oBAAoB,CAe9E;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA4BvG;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6B1F"}