@spikard/node 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -1,67 +1,3 @@
-interface StreamingResponseInit {
-    statusCode?: number;
-    headers?: Record<string, string>;
-}
-declare const STREAM_HANDLE_PROP: "__spikard_stream_handle";
-type StreamChunk = JsonValue | string | Buffer | Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined;
-type ChunkIterator = AsyncIterator<StreamChunk> & AsyncIterable<StreamChunk>;
-type StreamingHandle = {
-    kind: "native";
-    handle: number;
-    init: StreamingResponseInit;
-} | {
-    kind: "js";
-    iterator: ChunkIterator;
-    init: StreamingResponseInit;
-};
-declare class StreamingResponse {
-    readonly [STREAM_HANDLE_PROP]: StreamingHandle;
-    constructor(stream: AsyncIterable<StreamChunk> | AsyncIterator<StreamChunk>, init?: StreamingResponseInit);
-}
-
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonValue[] | {
-    [Key in string]: JsonValue;
-};
-type JsonRecord = Record<string, JsonValue>;
-type MaybePromise<T> = T | Promise<T>;
-interface Base64EncodedBody {
-    __spikard_base64__: string;
-}
-type HandlerBody = JsonValue | Base64EncodedBody | null;
-interface StructuredHandlerResponse {
-    status?: number;
-    statusCode?: number;
-    headers?: Record<string, string>;
-    body?: HandlerBody;
-}
-type HandlerResult = StructuredHandlerResponse | JsonValue | StreamingResponse | undefined;
-type HandlerFunction<TReturn extends HandlerResult = HandlerResult> = (request: Request) => MaybePromise<TReturn>;
-type NativeHandlerFunction<TReturn extends HandlerResult = HandlerResult> = (requestJson: string) => MaybePromise<TReturn | string>;
-type WebSocketHandler = (message: unknown) => MaybePromise<unknown>;
-interface WebSocketOptions {
-    onConnect?: () => MaybePromise<void>;
-    onDisconnect?: () => MaybePromise<void>;
-    messageSchema?: unknown;
-    responseSchema?: unknown;
-    handlerName?: string;
-}
-
-interface Request {
-    method: string;
-    path: string;
-    params: Record<string, string>;
-    pathParams: Record<string, string>;
-    query: Record<string, string>;
-    queryParams: Record<string, string>;
-    headers: Record<string, string>;
-    cookies: Record<string, string>;
-    body: Buffer | null;
-    dependencies: Record<string, unknown> | undefined;
-    json<T = JsonValue>(): T;
-    form(): Record<string, string>;
-}
-
 interface CompressionConfig {
     gzip?: boolean;
     brotli?: boolean;
@@ -147,62 +83,6 @@ interface ServerConfig {
     jsonrpc?: JsonRpcConfig | null;
 }
 
-interface ServerOptions {
-    host?: string;
-    port?: number;
-}
-declare function runServer(app: SpikardApp, config?: ServerConfig | ServerOptions): void;
-
-type DependencyValue = unknown;
-type DependencyFactory = (dependencies: Record<string, DependencyValue>) => MaybePromise<DependencyValue>;
-interface DependencyOptions {
-    dependsOn?: string[];
-    singleton?: boolean;
-    cacheable?: boolean;
-}
-interface DependencyDescriptor {
-    isFactory: boolean;
-    value?: DependencyValue | undefined;
-    factory?: DependencyFactory | undefined;
-    dependsOn: string[];
-    singleton: boolean;
-    cacheable: boolean;
-}
-type LifecycleHookPayload = Request | StructuredHandlerResponse;
-type LifecycleHookFunction = (payload: LifecycleHookPayload) => MaybePromise<LifecycleHookPayload>;
-interface LifecycleHooks {
-    onRequest: LifecycleHookFunction[];
-    preValidation: LifecycleHookFunction[];
-    preHandler: LifecycleHookFunction[];
-    onResponse: LifecycleHookFunction[];
-    onError: LifecycleHookFunction[];
-}
-declare class Spikard implements SpikardApp {
-    routes: RouteMetadata[];
-    handlers: Record<string, HandlerFunction | NativeHandlerFunction>;
-    websocketRoutes: RouteMetadata[];
-    websocketHandlers: Record<string, Record<string, unknown>>;
-    lifecycleHooks: LifecycleHooks;
-    dependencies: Record<string, DependencyDescriptor>;
-    addRoute(metadata: RouteMetadata, handler: HandlerFunction | NativeHandlerFunction): void;
-    websocket(path: string, handler: WebSocketHandler, options?: WebSocketOptions): void;
-    run(options?: ServerOptions): void;
-    onRequest(hook: LifecycleHookFunction): LifecycleHookFunction;
-    preValidation(hook: LifecycleHookFunction): LifecycleHookFunction;
-    preHandler(hook: LifecycleHookFunction): LifecycleHookFunction;
-    onResponse(hook: LifecycleHookFunction): LifecycleHookFunction;
-    onError(hook: LifecycleHookFunction): LifecycleHookFunction;
-    provide(key: string, valueOrFactory: DependencyValue | DependencyFactory, options?: DependencyOptions): this;
-    getLifecycleHooks(): LifecycleHooks;
-}
-
-declare function run(work: () => void | Promise<void>): void;
-
-declare const background_run: typeof run;
-declare namespace background {
-  export { background_run as run };
-}
-
 type GrpcMetadata = Record<string, string>;
 interface GrpcRequest {
     serviceName: string;
@@ -214,9 +94,37 @@ interface GrpcResponse {
     payload: Buffer;
     metadata?: GrpcMetadata;
 }
+interface GrpcClientStreamRequest {
+    serviceName: string;
+    methodName: string;
+    metadata: GrpcMetadata;
+    messages: Buffer[];
+}
+interface GrpcServerStreamResponse {
+    messages: Buffer[];
+}
+interface GrpcBidiStreamRequest {
+    serviceName: string;
+    methodName: string;
+    metadata: GrpcMetadata;
+    messages: Buffer[];
+}
+interface GrpcBidiStreamResponse {
+    messages: Buffer[];
+    metadata?: GrpcMetadata;
+}
 interface GrpcHandler {
     handleRequest(request: GrpcRequest): Promise<GrpcResponse>;
 }
+interface GrpcServerStreamingHandler {
+    handleServerStream(request: GrpcRequest): Promise<GrpcServerStreamResponse>;
+}
+interface GrpcClientStreamingHandler {
+    handleClientStream(request: GrpcClientStreamRequest): Promise<GrpcResponse>;
+}
+interface GrpcBidirectionalStreamingHandler {
+    handleBidiStream(request: GrpcBidiStreamRequest): Promise<GrpcBidiStreamResponse>;
+}
 declare enum GrpcStatusCode {
     OK = 0,
     CANCELLED = 1,
@@ -240,9 +148,29 @@ declare class GrpcError extends Error {
     readonly code: GrpcStatusCode;
     constructor(code: GrpcStatusCode, message: string);
 }
-interface GrpcServiceConfig {
+type GrpcRpcMode = "unary" | "serverStreaming" | "clientStreaming" | "bidirectionalStreaming";
+type GrpcMethodHandler = GrpcHandler | GrpcServerStreamingHandler | GrpcClientStreamingHandler | GrpcBidirectionalStreamingHandler;
+interface GrpcMethodConfig {
     serviceName: string;
-    handler: GrpcHandler;
+    methodName: string;
+    rpcMode: GrpcRpcMode;
+    handler: GrpcMethodHandler;
+}
+declare class GrpcService {
+    private readonly methods;
+    private methodKey;
+    private registerMethod;
+    registerUnary(serviceName: string, methodName: string, handler: GrpcHandler): this;
+    registerServerStreaming(serviceName: string, methodName: string, handler: GrpcServerStreamingHandler): this;
+    registerClientStreaming(serviceName: string, methodName: string, handler: GrpcClientStreamingHandler): this;
+    registerBidirectionalStreaming(serviceName: string, methodName: string, handler: GrpcBidirectionalStreamingHandler): this;
+    unregister(serviceName: string, methodName: string): void;
+    getMethod(serviceName: string, methodName: string): GrpcMethodConfig | undefined;
+    serviceNames(): string[];
+    methodNames(serviceName: string): string[];
+    hasMethod(serviceName: string, methodName: string): boolean;
+    entries(): GrpcMethodConfig[];
+    handleRequest(request: GrpcRequest): Promise<GrpcResponse>;
 }
 type UnaryHandlerResult<TResponse> = TResponse | {
     response: TResponse;
@@ -257,6 +185,128 @@ declare function createUnaryHandler<TRequest, TResponse>(methodName: string, han
 }): GrpcHandler;
 declare function createServiceHandler(methods: Record<string, GrpcHandler>): GrpcHandler;
 
+interface StreamingResponseInit {
+    statusCode?: number;
+    headers?: Record<string, string>;
+}
+declare const STREAM_HANDLE_PROP: "__spikard_stream_handle";
+type StreamChunk = JsonValue | string | Buffer | Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined;
+type ChunkIterator = AsyncIterator<StreamChunk> & AsyncIterable<StreamChunk>;
+type StreamingHandle = {
+    kind: "native";
+    handle: number;
+    init: StreamingResponseInit;
+} | {
+    kind: "js";
+    iterator: ChunkIterator;
+    init: StreamingResponseInit;
+};
+declare class StreamingResponse {
+    readonly [STREAM_HANDLE_PROP]: StreamingHandle;
+    constructor(stream: AsyncIterable<StreamChunk> | AsyncIterator<StreamChunk>, init?: StreamingResponseInit);
+}
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [Key in string]: JsonValue;
+};
+type JsonRecord = Record<string, JsonValue>;
+type MaybePromise<T> = T | Promise<T>;
+interface Base64EncodedBody {
+    __spikard_base64__: string;
+}
+type HandlerBody = JsonValue | Base64EncodedBody | null;
+interface StructuredHandlerResponse {
+    status?: number;
+    statusCode?: number;
+    headers?: Record<string, string>;
+    body?: HandlerBody;
+}
+type HandlerResult = StructuredHandlerResponse | JsonValue | StreamingResponse | undefined;
+type HandlerFunction<TReturn extends HandlerResult = HandlerResult> = (request: Request) => MaybePromise<TReturn>;
+type NativeHandlerFunction<TReturn extends HandlerResult = HandlerResult> = (requestJson: string) => MaybePromise<TReturn | string>;
+type WebSocketHandler = (message: unknown) => MaybePromise<unknown>;
+interface WebSocketOptions {
+    onConnect?: () => MaybePromise<void>;
+    onDisconnect?: () => MaybePromise<void>;
+    messageSchema?: unknown;
+    responseSchema?: unknown;
+    handlerName?: string;
+}
+
+interface Request {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    pathParams: Record<string, string>;
+    query: Record<string, string>;
+    queryParams: Record<string, string>;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    body: Buffer | null;
+    dependencies: Record<string, unknown> | undefined;
+    json<T = JsonValue>(): T;
+    form(): Record<string, string>;
+}
+
+type DependencyValue = unknown;
+type DependencyFactory = (dependencies: Record<string, DependencyValue>) => MaybePromise<DependencyValue>;
+interface DependencyOptions {
+    dependsOn?: string[];
+    singleton?: boolean;
+    cacheable?: boolean;
+}
+interface DependencyDescriptor {
+    isFactory: boolean;
+    value?: DependencyValue | undefined;
+    factory?: DependencyFactory | undefined;
+    dependsOn: string[];
+    singleton: boolean;
+    cacheable: boolean;
+}
+type LifecycleHookPayload = Request | StructuredHandlerResponse;
+type LifecycleHookFunction = (payload: LifecycleHookPayload) => MaybePromise<LifecycleHookPayload>;
+interface LifecycleHooks {
+    onRequest: LifecycleHookFunction[];
+    preValidation: LifecycleHookFunction[];
+    preHandler: LifecycleHookFunction[];
+    onResponse: LifecycleHookFunction[];
+    onError: LifecycleHookFunction[];
+}
+declare class Spikard implements SpikardApp {
+    routes: RouteMetadata[];
+    handlers: Record<string, HandlerFunction | NativeHandlerFunction>;
+    websocketRoutes: RouteMetadata[];
+    websocketHandlers: Record<string, Record<string, unknown>>;
+    grpcMethods: GrpcMethodRegistration[];
+    grpcHandlers: Record<string, Record<string, unknown>>;
+    lifecycleHooks: LifecycleHooks;
+    dependencies: Record<string, DependencyDescriptor>;
+    addRoute(metadata: RouteMetadata, handler: HandlerFunction | NativeHandlerFunction): void;
+    websocket(path: string, handler: WebSocketHandler, options?: WebSocketOptions): void;
+    addGrpcUnary(serviceName: string, methodName: string, handler: GrpcHandler): this;
+    addGrpcServerStreaming(serviceName: string, methodName: string, handler: GrpcServerStreamingHandler): this;
+    addGrpcClientStreaming(serviceName: string, methodName: string, handler: GrpcClientStreamingHandler): this;
+    addGrpcBidirectionalStreaming(serviceName: string, methodName: string, handler: GrpcBidirectionalStreamingHandler): this;
+    private registerGrpcMethod;
+    useGrpc(service: GrpcService): this;
+    run(config?: ServerConfig): void;
+    onRequest(hook: LifecycleHookFunction): LifecycleHookFunction;
+    preValidation(hook: LifecycleHookFunction): LifecycleHookFunction;
+    preHandler(hook: LifecycleHookFunction): LifecycleHookFunction;
+    onResponse(hook: LifecycleHookFunction): LifecycleHookFunction;
+    onError(hook: LifecycleHookFunction): LifecycleHookFunction;
+    provide(key: string, valueOrFactory: DependencyValue | DependencyFactory, options?: DependencyOptions): this;
+    getLifecycleHooks(): LifecycleHooks;
+}
+
+declare function run(work: () => void | Promise<void>): void;
+
+declare const background_run: typeof run;
+declare namespace background {
+  export { background_run as run };
+}
+
 declare function wrapHandler(handler: HandlerFunction): NativeHandlerFunction;
 declare function wrapBodyHandler<TBody = unknown>(handler: (body: TBody, request: Request) => MaybePromise<HandlerResult>): NativeHandlerFunction;
 
@@ -280,6 +330,8 @@ declare function put(path: string, options?: Omit<RouteOptions, "methods">): (ha
 declare function del(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
 declare function patch(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
 
+declare function runServer(app: SpikardApp, config?: ServerConfig): void;
+
 interface NativeTestResponse {
     statusCode: number;
     headers(): Record<string, string>;
@@ -402,14 +454,22 @@ interface RouteMetadata {
     is_async: boolean;
     cors?: CorsConfig | undefined;
 }
+interface GrpcMethodRegistration {
+    serviceName: string;
+    methodName: string;
+    rpcMode: GrpcRpcMode;
+    handlerName: string;
+}
 interface SpikardApp {
     routes: RouteMetadata[];
     handlers: Record<string, HandlerFunction | NativeHandlerFunction>;
     websocketRoutes?: RouteMetadata[];
     websocketHandlers?: Record<string, Record<string, unknown>>;
+    grpcMethods?: GrpcMethodRegistration[];
+    grpcHandlers?: Record<string, Record<string, unknown>>;
     config?: ServerConfig;
     lifecycleHooks?: Partial<LifecycleHooks>;
     dependencies?: Record<string, unknown>;
 }
 
-export { type ApiKeyConfig, type Base64EncodedBody, type Body, type CompressionConfig, type ContactInfo, type CorsConfig, type DependencyFactory, type DependencyOptions, type DependencyValue, type FileParam, GrpcError, type GrpcHandler, type GrpcMetadata, type GrpcRequest, type GrpcResponse, type GrpcServiceConfig, GrpcStatusCode, type HandlerFunction, type HandlerResult, type JsonPrimitive, type JsonRecord, type JsonRpcConfig, type JsonSchema, type JsonValue, type JwtConfig, type LicenseInfo, type LifecycleHookFunction, type LifecycleHooks, type MaybePromise, type NativeHandlerFunction, type OpenApiConfig, type Path, type Query, QueryDefault, type RateLimitConfig, type Request, type RouteMetadata, type RouteOptions, type SecuritySchemeInfo, type ServerConfig, type ServerInfo, type ServerOptions, Spikard, type SpikardApp, type StaticFilesConfig, StreamingResponse, type StreamingResponseInit, type StructuredHandlerResponse, TestClient, type TestResponse, UploadFile, type WebSocketHandler, type WebSocketOptions, background, createServiceHandler, createUnaryHandler, del, get, patch, post, put, route, runServer, wrapBodyHandler, wrapHandler };
+export { type ApiKeyConfig, type Base64EncodedBody, type Body, type CompressionConfig, type ContactInfo, type CorsConfig, type DependencyFactory, type DependencyOptions, type DependencyValue, type FileParam, type GrpcBidiStreamRequest, type GrpcBidiStreamResponse, type GrpcBidirectionalStreamingHandler, type GrpcClientStreamRequest, type GrpcClientStreamingHandler, GrpcError, type GrpcHandler, type GrpcMetadata, type GrpcMethodConfig, type GrpcMethodHandler, type GrpcMethodRegistration, type GrpcRequest, type GrpcResponse, type GrpcRpcMode, type GrpcServerStreamResponse, type GrpcServerStreamingHandler, GrpcService, GrpcStatusCode, type HandlerFunction, type HandlerResult, type JsonPrimitive, type JsonRecord, type JsonRpcConfig, type JsonSchema, type JsonValue, type JwtConfig, type LicenseInfo, type LifecycleHookFunction, type LifecycleHooks, type MaybePromise, type NativeHandlerFunction, type OpenApiConfig, type Path, type Query, QueryDefault, type RateLimitConfig, type Request, type RouteMetadata, type RouteOptions, type SecuritySchemeInfo, type ServerConfig, type ServerInfo, Spikard, type SpikardApp, type StaticFilesConfig, StreamingResponse, type StreamingResponseInit, type StructuredHandlerResponse, TestClient, type TestResponse, UploadFile, type WebSocketHandler, type WebSocketOptions, background, createServiceHandler, createUnaryHandler, del, get, patch, post, put, route, runServer, wrapBodyHandler, wrapHandler };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   GrpcError: () => GrpcError,
+  GrpcService: () => GrpcService,
   GrpcStatusCode: () => GrpcStatusCode,
   Spikard: () => Spikard,
   StreamingResponse: () => StreamingResponse,
@@ -51,7 +52,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
@@ -599,6 +600,8 @@ var Spikard = class {
   handlers = {};
   websocketRoutes = [];
   websocketHandlers = {};
+  grpcMethods = [];
+  grpcHandlers = {};
   lifecycleHooks = {
     onRequest: [],
     preValidation: [],
@@ -642,13 +645,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
@@ -874,6 +975,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) {
@@ -1807,6 +2037,7 @@ var TestClient = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GrpcError,
+  GrpcService,
   GrpcStatusCode,
   Spikard,
   StreamingResponse,