@spikard/node 0.12.0 → 0.13.0

package/dist/index.mjs

@@ -548,6 +548,8 @@ var Spikard = class {
   handlers = {};
   websocketRoutes = [];
   websocketHandlers = {};
+  grpcMethods = [];
+  grpcHandlers = {};
   lifecycleHooks = {
     onRequest: [],
     preValidation: [],
@@ -591,13 +593,111 @@ var Spikard = class {
     this.websocketRoutes.push(route2);
     this.websocketHandlers[handlerName] = handlerWrapper;
   }
+  /**
+   * Register a unary gRPC method on the application.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - gRPC method name
+   * @param handler - gRPC handler implementation
+   * @returns The application for chaining
+   */
+  addGrpcUnary(serviceName, methodName, handler) {
+    if (typeof handler?.handleRequest !== "function") {
+      throw new TypeError("Unary handler must implement handleRequest(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "unary", {
+      handleRequest: (request) => handler.handleRequest(request)
+    });
+  }
+  addGrpcServerStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleServerStream !== "function") {
+      throw new TypeError("Server-streaming handler must implement handleServerStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "serverStreaming", {
+      handleServerStream: (request) => handler.handleServerStream(request)
+    });
+  }
+  addGrpcClientStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleClientStream !== "function") {
+      throw new TypeError("Client-streaming handler must implement handleClientStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "clientStreaming", {
+      handleClientStream: (request) => handler.handleClientStream(request)
+    });
+  }
+  addGrpcBidirectionalStreaming(serviceName, methodName, handler) {
+    if (typeof handler?.handleBidiStream !== "function") {
+      throw new TypeError("Bidirectional-streaming handler must implement handleBidiStream(request)");
+    }
+    return this.registerGrpcMethod(serviceName, methodName, "bidirectionalStreaming", {
+      handleBidiStream: (request) => handler.handleBidiStream(request)
+    });
+  }
+  registerGrpcMethod(serviceName, methodName, rpcMode, handlerWrapper) {
+    if (!serviceName) {
+      throw new Error("Service name cannot be empty");
+    }
+    if (!methodName) {
+      throw new Error("Method name cannot be empty");
+    }
+    const previous = this.grpcMethods.find(
+      (entry) => entry.serviceName === serviceName && entry.methodName === methodName
+    );
+    if (previous) {
+      delete this.grpcHandlers[previous.handlerName];
+    }
+    const handlerName = `grpc_${this.grpcMethods.length}_${serviceName}_${methodName}`.replace(/[^a-zA-Z0-9_]/g, "_");
+    this.grpcHandlers[handlerName] = handlerWrapper;
+    this.grpcMethods = this.grpcMethods.filter(
+      (entry) => !(entry.serviceName === serviceName && entry.methodName === methodName)
+    );
+    this.grpcMethods.push({ serviceName, methodName, rpcMode, handlerName });
+    return this;
+  }
+  /**
+   * Mount all handlers from a gRPC service registry on the application.
+   *
+   * @param service - Registry containing one or more service methods
+   * @returns The application for chaining
+   */
+  useGrpc(service) {
+    for (const method of service.entries()) {
+      switch (method.rpcMode) {
+        case "unary":
+          this.addGrpcUnary(method.serviceName, method.methodName, method.handler);
+          break;
+        case "serverStreaming":
+          this.addGrpcServerStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+        case "clientStreaming":
+          this.addGrpcClientStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+        case "bidirectionalStreaming":
+          this.addGrpcBidirectionalStreaming(
+            method.serviceName,
+            method.methodName,
+            method.handler
+          );
+          break;
+      }
+    }
+    return this;
+  }
   /**
    * Run the server
    *
-   * @param options - Server configuration
+   * @param config - Server configuration
    */
-  run(options = {}) {
-    runServer(this, options);
+  run(config = {}) {
+    runServer(this, config);
   }
   /**
    * Register an onRequest lifecycle hook
@@ -823,6 +923,135 @@ var GrpcError = class extends Error {
     this.name = "GrpcError";
   }
 };
+var GrpcService = class {
+  methods = /* @__PURE__ */ new Map();
+  methodKey(serviceName, methodName) {
+    return `${serviceName}/${methodName}`;
+  }
+  registerMethod(config) {
+    if (!config.serviceName) {
+      throw new Error("Service name cannot be empty");
+    }
+    if (!config.methodName) {
+      throw new Error("Method name cannot be empty");
+    }
+    switch (config.rpcMode) {
+      case "unary":
+        if (typeof config.handler?.handleRequest !== "function") {
+          throw new TypeError("Unary handler must implement handleRequest(request)");
+        }
+        break;
+      case "serverStreaming":
+        if (typeof config.handler?.handleServerStream !== "function") {
+          throw new TypeError("Server-streaming handler must implement handleServerStream(request)");
+        }
+        break;
+      case "clientStreaming":
+        if (typeof config.handler?.handleClientStream !== "function") {
+          throw new TypeError("Client-streaming handler must implement handleClientStream(request)");
+        }
+        break;
+      case "bidirectionalStreaming":
+        if (typeof config.handler?.handleBidiStream !== "function") {
+          throw new TypeError("Bidirectional-streaming handler must implement handleBidiStream(request)");
+        }
+        break;
+    }
+    this.methods.set(this.methodKey(config.serviceName, config.methodName), config);
+    return this;
+  }
+  /**
+   * Register a unary handler for a fully-qualified service method.
+   *
+   * @param serviceName - Service name such as `mypackage.UserService`
+   * @param methodName - Method name such as `GetUser`
+   * @param handler - Handler implementation for that method
+   * @returns The registry for chaining
+   */
+  registerUnary(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "unary", handler });
+  }
+  registerServerStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "serverStreaming", handler });
+  }
+  registerClientStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "clientStreaming", handler });
+  }
+  registerBidirectionalStreaming(serviceName, methodName, handler) {
+    return this.registerMethod({ serviceName, methodName, rpcMode: "bidirectionalStreaming", handler });
+  }
+  /**
+   * Remove a handler from the registry.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   */
+  unregister(serviceName, methodName) {
+    if (!this.methods.delete(this.methodKey(serviceName, methodName))) {
+      throw new Error(`No handler registered for method: ${serviceName}/${methodName}`);
+    }
+  }
+  /**
+   * Get the registration for a service method.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   * @returns The registered method configuration, if present
+   */
+  getMethod(serviceName, methodName) {
+    return this.methods.get(this.methodKey(serviceName, methodName));
+  }
+  /**
+   * List all registered service names.
+   *
+   * @returns Fully-qualified service names
+   */
+  serviceNames() {
+    return Array.from(new Set(Array.from(this.methods.values(), (entry) => entry.serviceName)));
+  }
+  methodNames(serviceName) {
+    return Array.from(this.methods.values()).filter((entry) => entry.serviceName === serviceName).map((entry) => entry.methodName);
+  }
+  /**
+   * Check whether a specific service method is registered.
+   *
+   * @param serviceName - Fully-qualified service name
+   * @param methodName - Method name
+   * @returns True when a handler is registered for the method
+   */
+  hasMethod(serviceName, methodName) {
+    return this.methods.has(this.methodKey(serviceName, methodName));
+  }
+  /**
+   * Return registered method entries.
+   */
+  entries() {
+    return Array.from(this.methods.values());
+  }
+  /**
+   * Route a unary request to the registered method handler.
+   *
+   * @param request - Incoming gRPC request
+   * @returns Promise resolving to the handler response
+   * @throws GrpcError when no service is registered
+   */
+  async handleRequest(request) {
+    const method = this.getMethod(request.serviceName, request.methodName);
+    if (!method) {
+      throw new GrpcError(
+        12 /* UNIMPLEMENTED */,
+        `No handler registered for method: ${request.serviceName}/${request.methodName}`
+      );
+    }
+    if (method.rpcMode !== "unary") {
+      throw new GrpcError(
+        12 /* UNIMPLEMENTED */,
+        `Method ${request.serviceName}/${request.methodName} is registered as ${method.rpcMode}`
+      );
+    }
+    return method.handler.handleRequest(request);
+  }
+};
 function createUnaryHandler(methodName, handler, requestType, responseType) {
   return {
     async handleRequest(request) {
@@ -1755,6 +1984,7 @@ var TestClient = class {
 };
 export {
   GrpcError,
+  GrpcService,
   GrpcStatusCode,
   Spikard,
   StreamingResponse,