@nexusts/grpc 0.7.0 → 0.7.1

package/README.md

@@ -15,7 +15,7 @@ This module is part of the NexusTS monorepo. Each module is published as its own
 Most apps start with just the core:
 
 ```bash
-bun add @nexusts/core reflect-metadata zod hono
+bun add @nexusts/core
 ```
 
 Then add this module only if you need it:
@@ -26,7 +26,7 @@ bun add @nexusts/grpc
 
 ## Peer dependencies
 
-None. This module is fully self-contained.
+**None.** No external runtime dependencies. `gRPC` is built into the Bun runtime. On Node.js, install `@grpc/grpc-js` and `@grpc/proto-loader` separately.
 
 ## Usage
 

package/dist/decorators.d.ts

@@ -0,0 +1,33 @@
+/**
+ * gRPC decorators.
+ *
+ *   @Injectable()
+ *   @GrpcService("UserService")
+ *   class UserServiceImpl {
+ *     @GrpcMethod("FindById")
+ *     async findById(request: { id: number }) {
+ *       return { name: "Alice", email: "alice@example.com" };
+ *     }
+ *   }
+ *
+ * The framework reads the metadata at start time and wires
+ * each method to the corresponding gRPC handler. The method
+ * name in the decorator must match the .proto file's method
+ * name (e.g. `FindById`, not `findById`).
+ */
+/**
+ * Mark a class as a gRPC service implementation. The `name`
+ * must match a `service` declaration in the .proto file.
+ */
+export declare function GrpcService(name: string): ClassDecorator;
+/**
+ * Mark a method as a gRPC handler. The `name` must match the
+ * method name in the .proto file. The method receives the
+ * request object and must return a `Promise<TResponse>` (for
+ * unary methods).
+ */
+export declare function GrpcMethod(name: string): MethodDecorator;
+/** Read the gRPC service name. Internal. */
+export declare function getGrpcServiceName(target: object): string | undefined;
+/** Read the bound method names for a gRPC service. Internal. */
+export declare function getGrpcMethodNames(target: object): Record<string, string>;

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `nexusjs/grpc` — gRPC integration for the Bun-native stack.
+ *
+ * Public API:
+ * - `GrpcService` — the main service. Owns the @grpc/grpc-js server
+ *   and the loaded proto definition.
+ * - `GrpcModule.forRoot(config)` — wires the service into the DI
+ *   container, registers service implementations, and prepares the
+ *   handlers. The user calls `start()` to bind the server to a
+ *   port.
+ * - `@GrpcService(name)` — class decorator marking an impl class.
+ * - `@GrpcMethod(name)` — method decorator binding a method to a
+ *   gRPC method declared in the `.proto` file.
+ * - `client<T>(name, { url })` — build a typed client for a gRPC
+ *   service. Methods return Promises.
+ *
+ * Optional peer dependencies:
+ *   - `@grpc/grpc-js` (^1.10.0)  — the server runtime
+ *   - `@grpc/proto-loader` (^0.7.0) — loads `.proto` files
+ *
+ * Install with:
+ *   bun add @grpc/grpc-js @grpc/proto-loader
+ *
+ * Quick start:
+ *
+ *   // user.proto
+ *   syntax = "proto3";
+ *   package user;
+ *   service UserService {
+ *     rpc FindById (UserRequest) returns (UserResponse);
+ *   }
+ *   message UserRequest { int32 id = 1; }
+ *   message UserResponse { string name = 1; string email = 2; }
+ *
+ *   // user.grpc.ts
+ *   @Injectable()
+ *   @GrpcService("UserService")
+ *   class UserServiceImpl {
+ *     @GrpcMethod("FindById")
+ *     async findById(req: { id: number }) {
+ *       return { name: "Alice", email: "alice@example.com" };
+ *     }
+ *   }
+ *
+ *   // app.module.ts
+ *   @Module({
+ *     imports: [GrpcModule.forRoot({
+ *       protoPath: "./proto/user.proto",
+ *       services: [UserServiceImpl],
+ *     })],
+ *   })
+ *   class AppModule {}
+ *
+ *   // main.ts
+ *   const app = new Application(AppModule);
+ *   const grpc = app.container.resolve(GrpcService);
+ *   await grpc.start();  // binds to 0.0.0.0:50051
+ *
+ *   // client usage (e.g. in another service)
+ *   const userClient = grpc.client<{ findById(req: { id: number }): Promise<{ name: string; email: string }> }>("UserService");
+ *   const user = await userClient.findById({ id: 1 });
+ *
+ * Unary methods only for v1. Streaming (server / client / bidi)
+ * is a future addition.
+ */
+export { GrpcService, GRPC_SERVICE_TOKEN } from "./service.js";
+export { GrpcModule } from "./module.js";
+export { GrpcService as GrpcServiceDecorator, GrpcMethod, getGrpcServiceName, getGrpcMethodNames, } from "./decorators.js";
+export type { GrpcConfig, GrpcMethodMeta, GrpcClient, GrpcClientOptions, } from "./types.js";

package/dist/index.js

@@ -236,7 +236,7 @@ function makeUnaryHandler(fn, instance) {
   };
 }
 // packages/grpc/src/module.ts
-import { Module } from "@nexusts/core/decorators/index.js";
+import { Module } from "@nexusts/core";
 class GrpcModule {
   static forRoot(config) {
     class ConfiguredGrpcModule {
@@ -281,5 +281,5 @@ export {
   GRPC_SERVICE_TOKEN
 };
 
-//# debugId=ECB12AA4CE8F00C764756E2164756E21
+//# debugId=68F9B756B6DC011B64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -4,9 +4,9 @@
   "sourcesContent": [
     "/**\n * `GrpcService` — the main gRPC service.\n *\n * Owns the @grpc/grpc-js server, the loaded proto definition, and\n * the registered service implementations. The service is\n * registered in the DI container; the user calls `start()` to\n * bind the server to a port.\n *\n *   const grpc = container.resolve(GrpcService);\n *   await grpc.start();\n *   // ...\n *   await grpc.stop();\n *\n * The framework also exposes a `client<T>('ServiceName')` helper\n * for creating typed clients against the same (or a different)\n * server. Clients returned by this method are async — each method\n * returns a Promise.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { resolve as resolvePath } from \"node:path\";\nimport {\n\tloadPackageDefinition,\n\tServer as GrpcServer,\n\tServerCredentials,\n\tcredentials as grpcCredentials,\n} from \"@grpc/grpc-js\";\nimport * as protoLoader from \"@grpc/proto-loader\";\nimport {\n\tgetGrpcMethodNames,\n\tgetGrpcServiceName,\n} from \"./decorators.js\";\nimport type { GrpcConfig } from \"./types.js\";\n// logger is injected via the service in production; we use\n// console here to avoid a circular dependency with @core/logger.\n\nexport const GRPC_SERVICE_TOKEN = Symbol.for(\"nexus:GrpcService\");\n\nexport class GrpcService {\n\treadonly name = \"grpc\";\n\t#config: Required<Omit<GrpcConfig, \"tls\" | \"onBound\">> &\n\t\tPick<GrpcConfig, \"tls\" | \"onBound\">;\n\t#server: GrpcServer | null = null;\n\t#bound = false;\n\t#proto: any = null;\n\t#instanceByService: Map<string, unknown> = new Map();\n\t#clientCtors: Map<string, new (url: string, creds: any) => any> = new Map();\n\t#resolve: (<T>(token: unknown) => T) | null = null;\n\t#host: string | null = null;\n\t#port: number | null = null;\n\n\tconstructor(config: GrpcConfig) {\n\t\tthis.#config = {\n\t\t\tprotoPath: config.protoPath,\n\t\t\tpackage: config.package ?? \"\",\n\t\t\tservices: config.services ?? [],\n\t\t\tport: config.port ?? 50051,\n\t\t\thost: config.host ?? \"0.0.0.0\",\n\t\t\ttls: config.tls,\n\t\t\tonBound: config.onBound,\n\t\t};\n\t}\n\n\t/** True if the server is currently bound to a port. */\n\tget isRunning(): boolean {\n\t\treturn this.#bound;\n\t}\n\n\t/** The actual host the server bound to. `null` until start(). */\n\tget host(): string | null {\n\t\treturn this.#host;\n\t}\n\n\t/** Inject a resolver function. Called by GrpcModule.forRoot(). */\n\tsetResolver(resolve: <T>(token: unknown) => T): void {\n\t\tthis.#resolve = resolve;\n\t}\n\n\t/** The actual port the server bound to. `null` until start(). */\n\tget port(): number | null {\n\t\treturn this.#port;\n\t}\n\n\t/**\n\t * Load the .proto file(s) and prepare the server.\n\t * Idempotent — call once at boot, before `start()`.\n\t */\n\tasync prepare(resolve: <T>(token: unknown) => T): Promise<void> {\n\t\t// Load proto(s)\n\t\tconst files = Array.isArray(this.#config.protoPath)\n\t\t\t? this.#config.protoPath\n\t\t\t: [this.#config.protoPath];\n\t\tfor (const f of files) {\n\t\t\tif (!existsSync(f)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[grpc] proto file not found: ${f}. ` +\n\t\t\t\t\t\t`Resolve the path relative to your project root.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\t// loadPackageDefinition takes a single PackageDefinition. We\n\t\t// load each .proto separately and merge them into one\n\t\t// package tree.\n\t\tconst merged: Record<string, unknown> = {};\n\t\tfor (const f of files) {\n\t\t\tconst def = protoLoader.loadSync(f, {\n\t\t\t\tkeepCase: false,\n\t\t\t\tlongs: String,\n\t\t\t\tenums: String,\n\t\t\t\tdefaults: true,\n\t\t\t\toneofs: true,\n\t\t\t});\n\t\t\tconst loaded = loadPackageDefinition(def);\n\t\t\tObject.assign(merged, loaded);\n\t\t}\n\t\tthis.#proto = merged;\n\n\t\t// Build the server and register services\n\t\tthis.#server = new GrpcServer();\n\t\tfor (const ServiceImpl of this.#config.services) {\n\t\t\tconst svcName = getGrpcServiceName(ServiceImpl);\n\t\t\tif (!svcName) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[grpc] service ${ServiceImpl.name} is missing @GrpcService(name)`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst methodNames = getGrpcMethodNames(ServiceImpl.prototype);\n\t\t\t// @grpc/proto-loader produces nested objects, so we walk\n\t\t\t// the package path: proto.<package>.<serviceName>.\n\t\t\tconst segments = this.#config.package\n\t\t\t\t? this.#config.package.split(\".\")\n\t\t\t\t: [];\n\t\t\tsegments.push(svcName);\n\t\t\tlet svcSpec: { service: any; prototype?: unknown } | Record<string, unknown> | undefined =\n\t\t\t\tthis.#proto as Record<string, unknown>;\n\t\t\tfor (const seg of segments) {\n\t\t\t\tif (svcSpec && typeof svcSpec === \"object\" && seg in svcSpec) {\n\t\t\t\t\tsvcSpec = (svcSpec as Record<string, unknown>)[seg] as typeof svcSpec;\n\t\t\t\t} else {\n\t\t\t\t\tsvcSpec = undefined;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (!svcSpec) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[grpc] service \"${segments.join(\".\")}\" not found in proto definition. ` +\n\t\t\t\t\t\t`Check the .proto file and the @GrpcService name.`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// Resolve the implementation from the DI container\n\t\t\tconst instance = resolve(ServiceImpl);\n\t\t\tthis.#instanceByService.set(svcName, instance);\n\n\t\t\t// Build the handler map. For each @GrpcMethod, wrap\n\t\t\t// the user's method so it can be called as\n\t\t\t// (call, callback) => void and we await the Promise.\n\t\t\tconst handlers: Record<string, any> = {};\n\t\t\tfor (const [methodKey, protoMethodName] of Object.entries(\n\t\t\t\tmethodNames,\n\t\t\t)) {\n\t\t\t\tconst fn = (instance as Record<string, (...args: unknown[]) => unknown>)[\n\t\t\t\t\tmethodKey\n\t\t\t\t];\n\t\t\t\tif (typeof fn !== \"function\") continue;\n\t\t\t\t// Bind the method to the instance so `this` is preserved\n\t\t\t\t// (the user's handler may rely on `this` to access\n\t\t\t\t// injected dependencies).\n\t\t\t\thandlers[protoMethodName] = makeUnaryHandler(fn, instance);\n\t\t\t}\n\n\t\t\t// svcSpec is the Client constructor; .service is the ServiceDefinition.\n\t\t\tthis.#server!.addService((svcSpec as { service: any }).service, handlers);\n\t\t\tthis.#clientCtors.set(svcName, svcSpec as unknown as new (...a: any[]) => any);\n\t\t}\n\t}\n\n\t/**\n\t * Bind the server to the configured host/port. Resolves when\n\t * the port is bound. Use `port: 0` in tests to let the OS\n\t * pick a free port; the actual port is available via the\n\t * `port` getter or the `onBound` callback.\n\t */\n\tasync start(): Promise<void> {\n\t\tif (this.#resolve && !this.#server) {\n\t\t\tawait this.prepare(this.#resolve);\n\t\t}\n\t\tif (!this.#server) {\n\t\t\tthrow new Error(\n\t\t\t\t\"[grpc] start() called before prepare(). Call prepare() first \" +\n\t\t\t\t\t\"(typically done automatically by the DI module).\",\n\t\t\t);\n\t\t}\n\t\tif (this.isRunning) return;\n\n\t\tconst creds = this.#config.tls\n\t\t\t? ServerCredentials.createSsl(\n\t\t\t\t\tthis.#config.tls.cert as Buffer,\n\t\t\t\t\tArray.isArray(this.#config.tls.key) ? this.#config.tls.key[0] : (this.#config.tls.key as Buffer),\n\t\t\t\t)\n\t\t\t: ServerCredentials.createInsecure();\n\n\t\tconst port: number = await new Promise((resolveP, rejectP) => {\n\t\t\t\t// bindAsync(port: \"host:port\", creds, callback) — the\n\t\t\t// first arg is a single string, not separate host/port.\n\t\t\t(this.#server as GrpcServer).bindAsync(\n\t\t\t\t`${this.#config.host}:${this.#config.port}`,\n\t\t\t\tcreds,\n\t\t\t\t(err: Error | null, p: number) => {\n\t\t\t\t\t\t\t\treturn err ? rejectP(err) : resolveP(p);\n\t\t\t\t},\n\t\t\t);\n\t\t});\n\t\tthis.#host = this.#config.host;\n\t\tthis.#port = port;\n\t\tthis.#bound = true;\n\t\tconsole.log(\n\t\t\t`✓ gRPC server listening on ${this.#config.tls ? \"https\" : \"http\"}://${this.#host}:${this.#port}`,\n\t\t);\n\t\tthis.#config.onBound?.(this.#host, this.#port);\n\t}\n\n\t/** Stop the server and release the port. */\n\tasync stop(): Promise<void> {\n\t\tif (!this.#server) return;\n\t\t// tryShutdown waits for all pending RPCs to complete. If\n\t\t// a client is hung, this can hang forever. Race it against\n\t\t// a 1s timeout and force-shutdown if it doesn't complete.\n\t\tawait Promise.race([\n\t\t\tnew Promise<void>((resolveP, rejectP) => {\n\t\t\t\t(this.#server as GrpcServer).tryShutdown((err?: Error) =>\n\t\t\t\t\terr ? rejectP(err) : resolveP(),\n\t\t\t\t);\n\t\t\t}),\n\t\t\tnew Promise<void>((resolveP) => setTimeout(resolveP, 1000)),\n\t\t]).catch(() => {\n\t\t\t(this.#server as GrpcServer).forceShutdown();\n\t\t});\n\t\tthis.#server = null;\n\t\tthis.#host = null;\n\t\tthis.#port = null;\n\t\tthis.#bound = false;\n\t}\n\n\t/**\n\t * Build a typed client for a gRPC service. The returned object\n\t * has one Promise-returning method per service method defined\n\t * in the .proto file. Method names are converted to\n\t * camelCase on the client side to match JS convention\n\t * (e.g. `FindById` → `findById`).\n\t */\n\tclient<T = Record<string, (...args: unknown[]) => Promise<unknown>>>(\n\t\tserviceName: string,\n\t\toptions: { url: string; tls?: boolean } = {\n\t\t\turl: `127.0.0.1:${this.#port ?? 50051}`,\n\t\t},\n\t): T {\n\t\tif (!this.#proto) {\n\t\t\tthrow new Error(\n\t\t\t\t\"[grpc] client() called before prepare(). \" +\n\t\t\t\t\t\"Did you forget to call grpc.start()?\",\n\t\t\t);\n\t\t}\n\t\t// Walk the nested proto package to find the service spec.\n\t\tconst segments = this.#config.package\n\t\t\t? this.#config.package.split(\".\")\n\t\t\t: [];\n\t\tsegments.push(serviceName);\n\t\tlet svcSpec: { service: any; prototype?: unknown } | Record<string, unknown> | undefined =\n\t\t\tthis.#proto as Record<string, unknown>;\n\t\tfor (const seg of segments) {\n\t\t\tif (svcSpec && typeof svcSpec === \"object\" && seg in svcSpec) {\n\t\t\t\tsvcSpec = (svcSpec as Record<string, unknown>)[seg] as typeof svcSpec;\n\t\t\t} else {\n\t\t\t\tsvcSpec = undefined;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\tif (!svcSpec) {\n\t\t\tthrow new Error(\n\t\t\t\t`[grpc] service \"${segments.join(\".\")}\" not found in proto definition`,\n\t\t\t);\n\t\t}\n\t\t// svcSpec is the Client constructor itself.\n\t\tconst ClientCtor = svcSpec as unknown as {\n\t\t\tnew (url: string, creds: unknown): Record<string, (...args: unknown[]) => unknown>;\n\t\t\tservice: Record<string, Record<string, unknown>>;\n\t\t};\n\t\tconst creds = options.tls\n\t\t\t? // @ts-ignore\n\t\t\t\trequire(\"@grpc/grpc-js\").credentials.createSsl()\n\t\t\t: // @ts-ignore\n\t\t\t\trequire(\"@grpc/grpc-js\").credentials.createInsecure();\n\t\tconst underlying = new ClientCtor(options.url, creds);\n\t\t// ServiceDefinition lists methods in PascalCase (proto form).\n\t\t// The client exposes them as camelCase on its prototype.\n\t\tconst protoMethodNames = Object.keys(ClientCtor.service);\n\t\tconst methodNames = protoMethodNames.map(\n\t\t\t(n) => n.charAt(0).toLowerCase() + n.slice(1),\n\t\t);\n\t\tconst wrapped: Record<string, (...args: unknown[]) => Promise<unknown>> = {};\n\t\tfor (const methodName of methodNames) {\n\t\t\t// @ts-ignore - method exists on the prototype at runtime.\n\t\t\tconst fn = underlying[methodName];\n\t\t\tif (typeof fn !== \"function\") continue;\n\t\t\twrapped[methodName] = (req: unknown) =>\n\t\t\t\tnew Promise((resolveP, rejectP) => {\n\t\t\t\t\tfn.call(underlying, req, (err: Error | null, res: unknown) => {\n\t\t\t\t\t\tif (err) {\n\t\t\t\t\t\t\trejectP(err);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tresolveP(res);\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t\t\t});\n\t\t}\n\t\treturn wrapped as unknown as T;\n\t}\n}\n\n/**\n * Wrap a user's async method so it can be passed to gRPC's\n * callback-style handlers. Translates thrown errors into gRPC's\n * status code 13 (INTERNAL) by default.\n */\nfunction makeUnaryHandler(fn: (...args: unknown[]) => unknown, instance: unknown) {\n\treturn (call: unknown, callback: (err: unknown, res?: unknown) => void) => {\n\t\tconst req = (call as { request: unknown }).request;\n\t\t// Bind the method to the instance so `this` is preserved.\n\t\t// Use .then/.catch so we can correctly forward both\n\t\t// synchronous throws and async rejections to gRPC.\n\t\tlet result: unknown;\n\t\ttry {\n\t\t\tresult = fn.call(instance, req);\n\t\t} catch (syncErr) {\n\t\t\tconst e = syncErr as Error;\n\t\t\tconst code = (e as Error & { code?: number }).code ?? 13;\n\t\t\tcallback({ code, details: e.message });\n\t\t\treturn;\n\t\t}\n\t\tPromise.resolve(result).then(\n\t\t\t(value) => callback(null, value),\n\t\t\t(err: Error) => {\n\t\t\t\tconst code = (err as Error & { code?: number }).code ?? 13;\n\t\t\t\t// gRPC expects a plain { code, details } object, NOT\n\t\t\t\t// an Error instance.\n\t\t\t\tcallback({ code, details: err.message });\n\t\t\t},\n\t\t);\n\t};\n}\n\nexport default GrpcService;\n",
     "/**\n * gRPC decorators.\n *\n *   @Injectable()\n *   @GrpcService(\"UserService\")\n *   class UserServiceImpl {\n *     @GrpcMethod(\"FindById\")\n *     async findById(request: { id: number }) {\n *       return { name: \"Alice\", email: \"alice@example.com\" };\n *     }\n *   }\n *\n * The framework reads the metadata at start time and wires\n * each method to the corresponding gRPC handler. The method\n * name in the decorator must match the .proto file's method\n * name (e.g. `FindById`, not `findById`).\n */\n\nconst GRPC_SERVICE_KEY = Symbol.for(\"nexus:grpc:service\");\nconst GRPC_METHOD_KEY = Symbol.for(\"nexus:grpc:method\");\n\n/**\n * Mark a class as a gRPC service implementation. The `name`\n * must match a `service` declaration in the .proto file.\n */\nexport function GrpcService(name: string): ClassDecorator {\n\treturn function (target: Function) {\n\t\tconst proto = (target as { prototype: object }).prototype ?? target;\n\t\t(proto as Record<symbol, unknown>)[GRPC_SERVICE_KEY] = { name };\n\t};\n}\n\n/**\n * Mark a method as a gRPC handler. The `name` must match the\n * method name in the .proto file. The method receives the\n * request object and must return a `Promise<TResponse>` (for\n * unary methods).\n */\nexport function GrpcMethod(name: string): MethodDecorator {\n\treturn function (\n\t\t_target: object,\n\t\tpropertyKey: string | symbol,\n\t\t_descriptor: PropertyDescriptor,\n\t) {\n\t\tconst proto = _target as Record<symbol, unknown>;\n\t\tproto[GRPC_METHOD_KEY] = proto[GRPC_METHOD_KEY] ?? {};\n\t\t(proto[GRPC_METHOD_KEY] as Record<string | symbol, string>)[\n\t\t\tpropertyKey\n\t\t] = name;\n\t\treturn _descriptor;\n\t};\n}\n\n/** Read the gRPC service name. Internal. */\nexport function getGrpcServiceName(target: object): string | undefined {\n\tconst t = (target as { prototype?: object }).prototype ?? target;\n\treturn (t as Record<symbol, { name?: string } | undefined>)[\n\t\tGRPC_SERVICE_KEY\n\t]?.name;\n}\n\n/** Read the bound method names for a gRPC service. Internal. */\nexport function getGrpcMethodNames(target: object): Record<string, string> {\n\tconst t = (target as { prototype?: object }).prototype ?? target;\n\treturn (\n\t\t((t as Record<symbol, unknown>)[GRPC_METHOD_KEY] as\n\t\t\t| Record<string, string>\n\t\t\t| undefined) ?? {}\n\t);\n}\n",
-    "/**\n * `GrpcModule` — wires `GrpcService` into the DI container.\n *\n *   @Module({\n *     imports: [\n *       GrpcModule.forRoot({\n *         protoPath: \"./proto/user.proto\",\n *         services: [UserServiceImpl],\n *         port: 50051,\n *       }),\n *     ],\n *   })\n *   class AppModule {}\n *\n * After boot, the user resolves `GrpcService` from the\n * container and calls `start()` / `stop()` to control the\n * gRPC server's lifecycle:\n *\n *   const grpc = container.resolve(GrpcService);\n *   await grpc.start();\n *   // ...\n *   await grpc.stop();\n *\n * The framework also auto-registers the service impl classes\n * as DI providers, so their `@Inject()`-decorated dependencies\n * are wired up automatically.\n */\n\nimport { Module } from \"@nexusts/core/decorators/index.js\";\nimport { GrpcService, GRPC_SERVICE_TOKEN } from \"./service.js\";\nimport type { GrpcConfig } from \"./types.js\";\n\n@Module({\n\tproviders: [GrpcService, { provide: GRPC_SERVICE_TOKEN, useExisting: GrpcService }],\n\texports: [GrpcService, GRPC_SERVICE_TOKEN],\n})\nexport class GrpcModule {\n\tstatic forRoot(config: GrpcConfig) {\n\t\t@Module({\n\t\t\tproviders: [\n\t\t\t\t{ provide: \"GRPC_CONFIG\", useValue: config },\n\t\t\t\t// Service impl classes must be registered as providers so\n\t\t\t\t// the DI container can instantiate them.\n\t\t\t\t...config.services,\n\t\t\t\t{\n\t\t\t\t\tprovide: GrpcService,\n\t\t\t\t\tuseFactory: (resolve: <T>(t: unknown) => T) => {\n\n\t\t\t\t\t\tconst svc = new GrpcService(config);\n\t\t\t\t\t\t// prepare() resolves the service impls from the\n\t\t\t\t\t\t// container and registers their handlers on the\n\t\t\t\t\t\t// gRPC server. The user calls start() later to\n\t\t\t\t\t\t// bind to a port.\n\t\t\t\t\t\tsvc.setResolver((t) => resolve(t));\n\t\t\t\t\t\treturn svc;\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t{ provide: GRPC_SERVICE_TOKEN, useExisting: GrpcService },\n\t\t\t],\n\t\t\texports: [GrpcService, GRPC_SERVICE_TOKEN, \"GRPC_CONFIG\", ...config.services],\n\t\t})\n\t\tclass ConfiguredGrpcModule {}\n\t\tObject.defineProperty(ConfiguredGrpcModule, \"name\", {\n\t\t\tvalue: \"ConfiguredGrpcModule\",\n\t\t});\n\t\treturn ConfiguredGrpcModule as unknown as typeof GrpcModule;\n\t}\n}\n"
+    "/**\n * `GrpcModule` — wires `GrpcService` into the DI container.\n *\n *   @Module({\n *     imports: [\n *       GrpcModule.forRoot({\n *         protoPath: \"./proto/user.proto\",\n *         services: [UserServiceImpl],\n *         port: 50051,\n *       }),\n *     ],\n *   })\n *   class AppModule {}\n *\n * After boot, the user resolves `GrpcService` from the\n * container and calls `start()` / `stop()` to control the\n * gRPC server's lifecycle:\n *\n *   const grpc = container.resolve(GrpcService);\n *   await grpc.start();\n *   // ...\n *   await grpc.stop();\n *\n * The framework also auto-registers the service impl classes\n * as DI providers, so their `@Inject()`-decorated dependencies\n * are wired up automatically.\n */\n\nimport { Module } from \"@nexusts/core\";\nimport { GrpcService, GRPC_SERVICE_TOKEN } from \"./service.js\";\nimport type { GrpcConfig } from \"./types.js\";\n\n@Module({\n\tproviders: [GrpcService, { provide: GRPC_SERVICE_TOKEN, useExisting: GrpcService }],\n\texports: [GrpcService, GRPC_SERVICE_TOKEN],\n})\nexport class GrpcModule {\n\tstatic forRoot(config: GrpcConfig) {\n\t\t@Module({\n\t\t\tproviders: [\n\t\t\t\t{ provide: \"GRPC_CONFIG\", useValue: config },\n\t\t\t\t// Service impl classes must be registered as providers so\n\t\t\t\t// the DI container can instantiate them.\n\t\t\t\t...config.services,\n\t\t\t\t{\n\t\t\t\t\tprovide: GrpcService,\n\t\t\t\t\tuseFactory: (resolve: <T>(t: unknown) => T) => {\n\n\t\t\t\t\t\tconst svc = new GrpcService(config);\n\t\t\t\t\t\t// prepare() resolves the service impls from the\n\t\t\t\t\t\t// container and registers their handlers on the\n\t\t\t\t\t\t// gRPC server. The user calls start() later to\n\t\t\t\t\t\t// bind to a port.\n\t\t\t\t\t\tsvc.setResolver((t) => resolve(t));\n\t\t\t\t\t\treturn svc;\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t{ provide: GRPC_SERVICE_TOKEN, useExisting: GrpcService },\n\t\t\t],\n\t\t\texports: [GrpcService, GRPC_SERVICE_TOKEN, \"GRPC_CONFIG\", ...config.services],\n\t\t})\n\t\tclass ConfiguredGrpcModule {}\n\t\tObject.defineProperty(ConfiguredGrpcModule, \"name\", {\n\t\t\tvalue: \"ConfiguredGrpcModule\",\n\t\t});\n\t\treturn ConfiguredGrpcModule as unknown as typeof GrpcModule;\n\t}\n}\n"
   ],
   "mappings": "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",
-  "debugId": "ECB12AA4CE8F00C764756E2164756E21",
+  "debugId": "68F9B756B6DC011B64756E2164756E21",
   "names": []
 }

package/dist/module.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `GrpcModule` — wires `GrpcService` into the DI container.
+ *
+ *   @Module({
+ *     imports: [
+ *       GrpcModule.forRoot({
+ *         protoPath: "./proto/user.proto",
+ *         services: [UserServiceImpl],
+ *         port: 50051,
+ *       }),
+ *     ],
+ *   })
+ *   class AppModule {}
+ *
+ * After boot, the user resolves `GrpcService` from the
+ * container and calls `start()` / `stop()` to control the
+ * gRPC server's lifecycle:
+ *
+ *   const grpc = container.resolve(GrpcService);
+ *   await grpc.start();
+ *   // ...
+ *   await grpc.stop();
+ *
+ * The framework also auto-registers the service impl classes
+ * as DI providers, so their `@Inject()`-decorated dependencies
+ * are wired up automatically.
+ */
+import type { GrpcConfig } from "./types.js";
+export declare class GrpcModule {
+    static forRoot(config: GrpcConfig): typeof GrpcModule;
+}

package/dist/service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `GrpcService` — the main gRPC service.
+ *
+ * Owns the @grpc/grpc-js server, the loaded proto definition, and
+ * the registered service implementations. The service is
+ * registered in the DI container; the user calls `start()` to
+ * bind the server to a port.
+ *
+ *   const grpc = container.resolve(GrpcService);
+ *   await grpc.start();
+ *   // ...
+ *   await grpc.stop();
+ *
+ * The framework also exposes a `client<T>('ServiceName')` helper
+ * for creating typed clients against the same (or a different)
+ * server. Clients returned by this method are async — each method
+ * returns a Promise.
+ */
+import type { GrpcConfig } from "./types.js";
+export declare const GRPC_SERVICE_TOKEN: unique symbol;
+export declare class GrpcService {
+    #private;
+    readonly name = "grpc";
+    constructor(config: GrpcConfig);
+    /** True if the server is currently bound to a port. */
+    get isRunning(): boolean;
+    /** The actual host the server bound to. `null` until start(). */
+    get host(): string | null;
+    /** Inject a resolver function. Called by GrpcModule.forRoot(). */
+    setResolver(resolve: <T>(token: unknown) => T): void;
+    /** The actual port the server bound to. `null` until start(). */
+    get port(): number | null;
+    /**
+     * Load the .proto file(s) and prepare the server.
+     * Idempotent — call once at boot, before `start()`.
+     */
+    prepare(resolve: <T>(token: unknown) => T): Promise<void>;
+    /**
+     * Bind the server to the configured host/port. Resolves when
+     * the port is bound. Use `port: 0` in tests to let the OS
+     * pick a free port; the actual port is available via the
+     * `port` getter or the `onBound` callback.
+     */
+    start(): Promise<void>;
+    /** Stop the server and release the port. */
+    stop(): Promise<void>;
+    /**
+     * Build a typed client for a gRPC service. The returned object
+     * has one Promise-returning method per service method defined
+     * in the .proto file. Method names are converted to
+     * camelCase on the client side to match JS convention
+     * (e.g. `FindById` → `findById`).
+     */
+    client<T = Record<string, (...args: unknown[]) => Promise<unknown>>>(serviceName: string, options?: {
+        url: string;
+        tls?: boolean;
+    }): T;
+}
+export default GrpcService;

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Public types for `nexusjs/grpc`.
+ *
+ * `nexusjs/grpc` is a reflection-based gRPC integration. The user
+ * provides a `.proto` file and a service implementation class
+ * with `@GrpcService` / `@GrpcMethod` decorators. The framework
+ * loads the proto at runtime and wires the methods to the
+ * implementation.
+ *
+ * The gRPC server runs on a separate port (it needs HTTP/2) and
+ * is started manually via `GrpcService.start()`. This keeps the
+ * Hono HTTP/1 server independent and lets the user choose the
+ * port.
+ *
+ * Cross-runtime: works on Bun and Node via `@grpc/grpc-js`
+ * (which is built on Node's `http2` module — Bun supports
+ * this via Node-API compatibility).
+ *
+ * Unary methods only for v1; streaming (server / client / bidi)
+ * is a future addition.
+ */
+import type { ServiceDefinition, UntypedServiceImplementation } from "@grpc/grpc-js";
+export interface GrpcConfig {
+    /**
+     * Path to one or more `.proto` files. Paths are resolved
+     * against the process's cwd.
+     */
+    protoPath: string | string[];
+    /**
+     * Optional override for the proto package name. If omitted,
+     * the package is taken from the `.proto` file. Useful when
+     * the .proto file has multiple `package` declarations.
+     */
+    package?: string;
+    /**
+     * Service implementations to register. Each class must be
+     * decorated with `@GrpcService('Name')` and have its methods
+     * decorated with `@GrpcMethod('ProtoMethodName')`.
+     */
+    services: Array<new (...args: never[]) => unknown>;
+    /** Port to bind the gRPC server to. Default: 50051. */
+    port?: number;
+    /** Host to bind the gRPC server to. Default: "0.0.0.0". */
+    host?: string;
+    /**
+     * TLS credentials. If omitted, the server runs in plaintext
+     * (h2c). For production, provide a `tls: { cert, key }` pair.
+     */
+    tls?: {
+        cert: Buffer | string;
+        key: Buffer | string;
+    };
+    /**
+     * Optional callback that runs after the server is bound. Useful
+     * for tests that need to know the actual port (when `port: 0`
+     * is used).
+     */
+    onBound?: (host: string, port: number) => void;
+}
+export interface GrpcMethodMeta {
+    /** Service name (matches `@GrpcService(name)`). */
+    serviceName: string;
+    /** Method name as it appears in the .proto file. */
+    methodName: string;
+}
+/**
+ * Build a typed client for a gRPC service. The returned object
+ * has one method per service method defined in the .proto file,
+ * with the right TypeScript signature.
+ */
+export type GrpcClient<T> = T;
+export interface GrpcClientOptions {
+    /** Service URL (e.g. "localhost:50051"). */
+    url: string;
+    /** Use TLS. Default: false (insecure). */
+    tls?: boolean;
+}
+export type { ServiceDefinition, UntypedServiceImplementation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusts/grpc",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "gRPC server + typed client (reflection-based)",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,20 +12,15 @@
       "import": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
+  "files": ["dist", "README.md"],
   "scripts": {
     "build": "bun run ../../build.ts"
   },
-  "keywords": [
-    "nexusts",
-    "framework",
-    "bun"
-  ],
+  "keywords": ["nexusts", "framework", "bun"],
   "license": "MIT",
+  
+  
   "dependencies": {
-    "@nexusts/core": "^0.7.0"
+    "@nexusts/core": "file:../core"
   }
 }