@yylego/grpc-to-http 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yangyile-yyle88-yylego
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# grpc-to-http
+
+Convert a TypeScript gRPC client into an HTTP client using Axios.
+
+---
+
+![grpc-to-http-overview](assets/grpc-to-http-overview.svg)
+
+---
+
+## CHINESE README
+
+[中文说明](README.zh.md)
+
+## Features
+
+- Convert protobuf-ts generated gRPC client invocations to HTTP/REST requests
+- Use Axios as the HTTP engine
+- Automatic path param extraction and rewriting
+- GET/POST/PUT/DELETE methods via `google.api.http` annotations
+- Snake_case to camelCase param name auto-conversion
+- Lightweight with minimum dependencies
+
+## Design
+
+When using [protobuf-ts](https://github.com/timostamm/protobuf-ts) to generate TypeScript gRPC clients, the generated code uses `stackIntercept` and `UnaryCall` as gRPC mechanisms. This package provides `executeGrpcToHttp` and `GrpcToHttpPromise` as drop-in replacements that route requests through HTTP/REST endpoints using Axios instead.
+
+The conversion reads `google.api.http` annotations from `.proto` files to decide:
+- HTTP method (GET/POST/PUT/DELETE)
+- URL path (with param substitution)
+- Request payload handling
+
+This is most convenient when the backend (e.g., [Kratos](https://github.com/go-kratos/kratos)) exposes both gRPC and HTTP endpoints, and the frontend uses HTTP without configuring a gRPC bridge.
+
+## Related Projects
+
+- [kratos-vue3](https://github.com/yylego/kratos-vue3) — Go package that integrates Vue3 frontend with Kratos backend, using this package to bridge gRPC and HTTP
+- [kratos-vue3-demo](https://github.com/kratos-examples/vue3) — Complete demo project showing how to use grpc-to-http with Kratos and Vue3
+
+## Setup
+
+```bash
+npm install @yylego/grpc-to-http
+```
+
+## Usage
+
+Import from the package:
+
+```typescript
+import { executeGrpcToHttp, GrpcToHttpException, grpcToHttpConfig } from '@yylego/grpc-to-http';
+import type { GrpcToHttpPromise } from '@yylego/grpc-to-http';
+```
+
+### API
+
+**`executeGrpcToHttp<I, O>(callType, transport, method, options, input)`**
+
+Execute a gRPC request via HTTP. Arguments:
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `callType` | `string` | The gRPC request type (e.g., "unary") |
+| `transport` | `RpcTransport` | The protobuf-ts transport mechanism |
+| `method` | `MethodInfo<I, O>` | The method info from protobuf-ts |
+| `options` | `RpcOptions` | Options including `baseUrl` and `meta` (headers) |
+| `input` | `I` | The request input object |
+
+Returns `GrpcToHttpPromise<I, O>` — a Promise that resolves to an Axios response.
+
+**`grpcToHttpConfig`**
+
+Configuration object. Supported options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | When `true`, prints request details to console |
+
+**`GrpcToHttpException`**
+
+Custom exception class thrown when conversion encounters issues (e.g., missing HTTP method annotation, missing path parameters). Use `instanceof` to distinguish from network exceptions:
+
+```typescript
+import { GrpcToHttpException } from '@yylego/grpc-to-http';
+
+try {
+    const response = await client.sayHello({ name: 'World' }, options);
+} catch (e) {
+    if (e instanceof GrpcToHttpException) {
+        console.log('Conversion exception:', e.message);
+    } else {
+        console.log('Network exception:', e);
+    }
+}
+```
+
+**Debug Output**
+
+When `grpcToHttpConfig.debug = true`, two lines are printed for each request:
+
+```
+[grpc-to-http] method=SayHello params={"name":"World"}
+[grpc-to-http] method=SayHello params={"name":"World"} POST http://localhost:8000/api/hello
+```
+
+The first line is printed on request entrance, the second line is printed once the HTTP request is constructed.
+
+### Code Sample
+
+```typescript
+// In a Vue component
+import { executeGrpcToHttp, grpcToHttpConfig } from '@yylego/grpc-to-http';
+
+// Enable debug mode (optional)
+grpcToHttpConfig.debug = true;
+
+const options: RpcOptions = {
+    baseUrl: 'http://localhost:8000',
+    meta: {
+        'Authorization': 'token-value-here'
+    }
+};
+
+// The generated client uses HTTP instead of gRPC
+const response = await client.sayHello({ name: 'World' }, options);
+```
+
+## Lint
+
+```bash
+npx tsc --noEmit
+```
+
+## Publish
+
+```bash
+npm publish --access=public
+```
+
+---
+
+## Previous Version
+
+This package was once published as [@yyle88/grpt](https://www.npmjs.com/package/@yyle88/grpt) on the [yyle88](https://github.com/yyle88) account.
+
+The `yyle88` account has been suspended, so `@yyle88/grpt` is discontinued. Please use `@yylego/grpc-to-http` instead.
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE).
+
+---
+
+## 💬 Contact & Feedback
+
+Contributions welcome! Submit bugs, suggest features, and contribute code:
+
+- 🐛 **Mistake found?** Open an issue on GitHub with reproduction steps
+- 💡 **New ideas?** Create an issue to discuss
+- 📖 **Documentation confusing?** Let us know so we can make improvements
+- 🚀 **Need new features?** Describe the use case to help us understand
+- ⚡ **Performance issue?** Help us optimize through detailed reports
+- 📢 **Want updates?** Watch the repo to get new releases and features
+- 💬 **Feedback?** We welcome suggestions and comments
+
+---
+
+## 🔧 Development
+
+New code contributions, follow this process:
+
+1. **Fork**: Fork the repo on GitHub (using the webpage UI).
+2. **Clone**: Clone the forked project (`git clone https://github.com/username/grpc-to-http.git`).
+3. **Navigate**: Navigate to the cloned project (`cd grpc-to-http`)
+4. **Branch**: Create a feature branch (`git checkout -b feature/xxx`).
+5. **Code**: Implement the changes with comprehensive tests
+6. **Testing**: Run `npx tsc --noEmit` to check TypeScript compilation
+7. **Documentation**: Update documentation to match client-facing changes
+8. **Stage**: Stage changes (`git add .`)
+9. **Commit**: Commit changes (`git commit -m "Add feature xxx"`)
+10. **Push**: Push to the branch (`git push origin feature/xxx`).
+11. **PR**: Open a merge request on GitHub (on the GitHub webpage) with a detailed description.
+
+Please make tests pass and include documentation updates.
+
+---
+
+## 🌟 Support
+
+Welcome to contribute to this project via submitting merge requests and reporting issues.
+
+**Project Support:**
+
+- ⭐ **Give GitHub Stars** if this project helps
+- 🤝 **Share with teammates** who use protobuf-ts with HTTP backends
+- 📝 **Write tech posts** about gRPC-to-HTTP conversion workflows
+- 🌟 **Join the ecosystem** - committed to supporting open source and the frontend development scene
+
+**Have Fun Coding with this package!** 🎉🎉🎉

package/README.zh.md

@@ -0,0 +1,201 @@
+# grpc-to-http
+
+将 TypeScript gRPC 客户端转换为基于 Axios 的 HTTP 客户端。
+
+---
+
+![grpc-to-http-overview](assets/grpc-to-http-overview.svg)
+
+---
+
+## 英文文档
+
+[ENGLISH README](README.md)
+
+## 功能特性
+
+- 将 protobuf-ts 生成的 gRPC 客户端调用转换为 HTTP/REST 请求
+- 使用 Axios 作为 HTTP 传输层
+- 自动提取和重写路径参数
+- 通过 `google.api.http` 注解支持 GET/POST/PUT/DELETE 方法
+- 自动将 snake_case 参数名转换为 camelCase
+- 轻量级，依赖极少
+
+## 设计思路
+
+使用 [protobuf-ts](https://github.com/timostamm/protobuf-ts) 生成 TypeScript gRPC 客户端时，生成的代码使用 `stackIntercept` 和 `UnaryCall` 进行 gRPC 传输。本包提供 `executeGrpcToHttp` 和 `GrpcToHttpPromise` 作为替代，通过 Axios 将请求转发到 HTTP/REST 端点。
+
+转换过程读取 `.proto` 文件中的 `google.api.http` 注解来确定：
+- HTTP 方法（GET/POST/PUT/DELETE）
+- URL 路径（含参数替换）
+- 请求体处理方式
+
+当后端（如 [Kratos](https://github.com/go-kratos/kratos)）同时暴露 gRPC 和 HTTP 端点时，前端可以直接使用 HTTP 调用，无需配置 gRPC 代理。
+
+## 关联项目
+
+- [kratos-vue3](https://github.com/yylego/kratos-vue3) — Go 包，将 Vue3 前端与 Kratos 后端集成，使用本包桥接 gRPC 和 HTTP
+- [kratos-vue3-demo](https://github.com/kratos-examples/vue3) — 完整的演示项目，展示如何配合 Kratos 和 Vue3 使用 grpc-to-http
+
+## 安装
+
+```bash
+npm install @yylego/grpc-to-http
+```
+
+## 使用
+
+从包中导入：
+
+```typescript
+import { executeGrpcToHttp, GrpcToHttpException, grpcToHttpConfig } from '@yylego/grpc-to-http';
+import type { GrpcToHttpPromise } from '@yylego/grpc-to-http';
+```
+
+### API
+
+**`executeGrpcToHttp<I, O>(callType, transport, method, options, input)`**
+
+通过 HTTP 执行 gRPC 调用。参数：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `callType` | `string` | gRPC 调用类型（如 "unary"） |
+| `transport` | `RpcTransport` | protobuf-ts 传输机制 |
+| `method` | `MethodInfo<I, O>` | protobuf-ts 方法信息 |
+| `options` | `RpcOptions` | 选项，包含 `baseUrl` 和 `meta`（请求头） |
+| `input` | `I` | 请求输入对象 |
+
+返回 `GrpcToHttpPromise<I, O>` — 解析为 Axios 响应的 Promise。
+
+**`grpcToHttpConfig`**
+
+配置对象。支持的选项：
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `debug` | `boolean` | `false` | 设为 `true` 时，在控制台打印请求详情 |
+
+**`GrpcToHttpException`**
+
+自定义异常类，在转换遇到问题时抛出（如缺少 HTTP 方法注解、缺少路径参数）。使用 `instanceof` 即可区分转换异常和网络异常：
+
+```typescript
+import { GrpcToHttpException } from '@yylego/grpc-to-http';
+
+try {
+    const response = await client.sayHello({ name: 'World' }, options);
+} catch (e) {
+    if (e instanceof GrpcToHttpException) {
+        console.log('转换异常:', e.message);
+    } else {
+        console.log('网络异常:', e);
+    }
+}
+```
+
+**调试输出**
+
+当 `grpcToHttpConfig.debug = true` 时，每次请求会打印两行日志：
+
+```
+[grpc-to-http] method=SayHello params={"name":"World"}
+[grpc-to-http] method=SayHello params={"name":"World"} POST http://localhost:8000/api/hello
+```
+
+第一行在请求入口处打印，第二行在构造完 HTTP 请求后打印。
+
+### 示例
+
+```typescript
+// 在 Vue 组件中
+import { executeGrpcToHttp, grpcToHttpConfig } from '@yylego/grpc-to-http';
+
+// 开启调试模式（可选）
+grpcToHttpConfig.debug = true;
+
+const options: RpcOptions = {
+    baseUrl: 'http://localhost:8000',
+    meta: {
+        'Authorization': 'token-value-here'
+    }
+};
+
+// 生成的客户端自动使用 HTTP 而非 gRPC
+const response = await client.sayHello({ name: 'World' }, options);
+```
+
+## 代码检查
+
+```bash
+npx tsc --noEmit
+```
+
+## 发布
+
+```bash
+npm publish --access=public
+```
+
+---
+
+## 旧版本说明
+
+本包的前身是 [@yyle88/grpt](https://www.npmjs.com/package/@yyle88/grpt)，由 [yyle88](https://github.com/yyle88) 发布。
+
+由于 `yyle88` 账号已被封禁，`@yyle88/grpt` 不再维护。请使用 `@yylego/grpc-to-http` 替代。
+
+---
+
+## 📄 许可证类型
+
+MIT 许可证 - 详见 [LICENSE](LICENSE)。
+
+---
+
+## 💬 联系与反馈
+
+非常欢迎贡献代码！报告 BUG、建议功能、贡献代码：
+
+- 🐛 **问题报告？** 在 GitHub 上提交问题并附上重现步骤
+- 💡 **新颖思路？** 创建 issue 讨论
+- 📖 **文档疑惑？** 报告问题，帮助我们完善文档
+- 🚀 **需要功能？** 分享使用场景，帮助理解需求
+- ⚡ **性能瓶颈？** 报告慢操作，协助解决性能问题
+- 📢 **关注进展？** 关注仓库以获取新版本和功能
+- 💬 **反馈意见？** 欢迎提出建议和意见
+
+---
+
+## 🔧 代码贡献
+
+新代码贡献，请遵循此流程：
+
+1. **Fork**：在 GitHub 上 Fork 仓库（使用网页界面）
+2. **克隆**：克隆 Fork 的项目（`git clone https://github.com/username/grpc-to-http.git`）
+3. **导航**：进入克隆的项目（`cd grpc-to-http`）
+4. **分支**：创建功能分支（`git checkout -b feature/xxx`）
+5. **编码**：实现更改并编写全面的测试
+6. **测试**：运行 `npx tsc --noEmit` 检查 TypeScript 编译
+7. **文档**：面向用户的更改需要更新文档
+8. **暂存**：暂存更改（`git add .`）
+9. **提交**：提交更改（`git commit -m "Add feature xxx"`）
+10. **推送**：推送到分支（`git push origin feature/xxx`）
+11. **PR**：在 GitHub 上打开 Merge Request（在 GitHub 网页上）并提供详细描述
+
+请确保测试通过并包含相关的文档更新。
+
+---
+
+## 🌟 项目支持
+
+非常欢迎通过提交 Merge Request 和报告问题来贡献此项目。
+
+**项目支持：**
+
+- ⭐ **给予星标** 如果项目对您有帮助
+- 🤝 **分享项目** 给团队成员和前端开发朋友
+- 📝 **撰写博客** 关于 gRPC 转 HTTP 的使用经验
+- 🌟 **加入生态** - 致力于支持开源和前端开发场景
+
+**祝你用这个包编程愉快！** 🎉🎉🎉

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { executeGrpcToHttp, GrpcToHttpException, grpcToHttpConfig } from './src/grpc-to-http.js';
+export type { GrpcToHttpPromise } from './src/grpc-to-http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { executeGrpcToHttp, GrpcToHttpException, grpcToHttpConfig } from './src/grpc-to-http.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/grpc-to-http.d.ts

@@ -0,0 +1,40 @@
+import type { RpcTransport, RpcOptions, MethodInfo } from '@protobuf-ts/runtime-rpc';
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+/**
+ * Configuration object for grpc-to-http.
+ * Modify these options to control package runtime settings.
+ */
+export declare const grpcToHttpConfig: {
+    /** Enable debug logging to console. Default: false. */
+    debug: boolean;
+};
+/**
+ * Custom exception class for grpc-to-http conversion failures.
+ * Allows callers to distinguish conversion exceptions from network exceptions via instanceof.
+ */
+export declare class GrpcToHttpException extends Error {
+    constructor(message: string);
+}
+/**
+ * Represents a promise that resolves to an Axios response containing the output-resp object.
+ *
+ * @template I - The type of the input-param object.
+ * @template O - The type of the output-resp object.
+ */
+export type GrpcToHttpPromise<I, O> = Promise<AxiosResponse<O, AxiosRequestConfig<I>>>;
+/**
+ * Performs a gRPC call over HTTP using the specified transport mechanism, method information, and provided options.
+ * Returns a promise that resolves to the Axios response containing the output-resp object.
+ *
+ * @template I - The type of the input-param object.
+ * @template O - The type of the output-resp object.
+ * @param callType - The type of the gRPC call (e.g., unary, server streaming).
+ * @param transport - The transport mechanism for the gRPC call.
+ * @param method - The method information for the gRPC call.
+ * @param options - The options for the gRPC call, including the base URL and metadata.
+ * @param input - The input-param object containing the request data.
+ * @returns A promise that resolves to the Axios response containing the output-resp object.
+ * @throws Will throw an error if the HTTP method is not defined or if a required parameter is missing.
+ */
+export declare function executeGrpcToHttp<I extends object, O extends object>(callType: string, transport: RpcTransport, method: MethodInfo<I, O>, options: RpcOptions, input: I): GrpcToHttpPromise<I, O>;
+//# sourceMappingURL=grpc-to-http.d.ts.map

package/dist/src/grpc-to-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc-to-http.d.ts","sourceRoot":"","sources":["../../src/grpc-to-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAA;AAElF,OAAO,KAAK,EAAC,kBAAkB,EAAE,aAAa,EAAC,MAAM,OAAO,CAAA;AAI5D;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IACzB,uDAAuD;;CAE1D,CAAA;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAChE,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACxB,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,CAAC,GACT,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CA2CzB"}

package/dist/src/grpc-to-http.js

@@ -0,0 +1,115 @@
+import axios from 'axios';
+import urlJoin from 'url-join';
+/**
+ * Configuration object for grpc-to-http.
+ * Modify these options to control package runtime settings.
+ */
+export const grpcToHttpConfig = {
+    /** Enable debug logging to console. Default: false. */
+    debug: false,
+};
+/**
+ * Custom exception class for grpc-to-http conversion failures.
+ * Allows callers to distinguish conversion exceptions from network exceptions via instanceof.
+ */
+export class GrpcToHttpException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GrpcToHttpException';
+    }
+}
+/**
+ * Performs a gRPC call over HTTP using the specified transport mechanism, method information, and provided options.
+ * Returns a promise that resolves to the Axios response containing the output-resp object.
+ *
+ * @template I - The type of the input-param object.
+ * @template O - The type of the output-resp object.
+ * @param callType - The type of the gRPC call (e.g., unary, server streaming).
+ * @param transport - The transport mechanism for the gRPC call.
+ * @param method - The method information for the gRPC call.
+ * @param options - The options for the gRPC call, including the base URL and metadata.
+ * @param input - The input-param object containing the request data.
+ * @returns A promise that resolves to the Axios response containing the output-resp object.
+ * @throws Will throw an error if the HTTP method is not defined or if a required parameter is missing.
+ */
+export function executeGrpcToHttp(callType, transport, method, options, input) {
+    if (grpcToHttpConfig.debug) {
+        console.debug(`[grpc-to-http] method=${method.name} params=${JSON.stringify(input)}`);
+    }
+    const baseUrl = options['baseUrl']; // base URL from RpcOptions
+    const apiHttp = method.options['google.api.http']; // HTTP mapping from proto annotations
+    const reqMethods = ['get', 'post', 'put', 'delete'];
+    const httpMethod = Object.keys(apiHttp).find((key) => reqMethods.includes(key));
+    if (!httpMethod) {
+        const message = Object.keys(apiHttp).length === 0
+            ? 'Request error - No HTTP method defined in GRPC'
+            : 'Request error - Non GET/POST/PUT/DELETE HTTP method defined in GRPC';
+        throw new GrpcToHttpException(message);
+    }
+    let uriPath = apiHttp[httpMethod];
+    let queryParams = undefined;
+    let requestBody = undefined;
+    if (apiHttp.body === '*') { // when body is '*', send the entire input as request body
+        requestBody = input;
+    }
+    else {
+        if (uriPath.includes('{') && uriPath.includes('}')) {
+            uriPath = rewritePathParam(uriPath, input);
+        }
+        else {
+            queryParams = input;
+        }
+    }
+    const fullUrl = urlJoin(baseUrl, uriPath);
+    if (grpcToHttpConfig.debug) {
+        console.debug(`[grpc-to-http] method=${method.name} params=${JSON.stringify(input)} ${httpMethod.toUpperCase()} ${fullUrl}`);
+    }
+    const axiosConfig = {
+        method: httpMethod,
+        url: fullUrl,
+        params: queryParams, // passed as URL query string (e.g. GET requests)
+        data: requestBody,
+        headers: options.meta ?? {}, // pass metadata as HTTP headers
+    };
+    return axios.request(axiosConfig);
+}
+/**
+ * Rewrites the URI path by replacing path parameters with corresponding values from the input-param object.
+ * If a parameter is not found in the input-param object, it attempts to convert the parameter name from snake_case to camelCase.
+ *
+ * @template T - The type of the input-param object.
+ * @param uriPath - The URI path containing parameters in the format `{param}`.
+ * @param input - The input-param object containing values for the parameters.
+ * @returns The URI path with parameters replaced by their corresponding values from the input-param object.
+ * @throws Will throw an error if a parameter is missing in the input-param object.
+ */
+function rewritePathParam(uriPath, input) {
+    const params = uriPath.match(/{(\w+)}/g);
+    if (params) {
+        params.forEach((param) => {
+            const paramName = param.slice(1, -1);
+            let value = input[paramName];
+            if (value === undefined) {
+                // try converting snake_case to camelCase (e.g. example_param_name -> exampleParamName)
+                const newParamName = toCamelCase(paramName);
+                value = input[newParamName];
+            }
+            if (value === undefined) {
+                throw new GrpcToHttpException(`MISSING PARAMETER: ${paramName}`);
+            }
+            uriPath = uriPath.replace(param, encodeURIComponent(String(value ?? '')));
+        });
+    }
+    return uriPath;
+}
+/**
+ * Converts a snake_case string to camelCase.
+ * For example, `example_param_name` will be converted to `exampleParamName`.
+ *
+ * @param paramName - The snake_case string to be converted.
+ * @returns The converted camelCase string.
+ */
+function toCamelCase(paramName) {
+    return paramName.replace(/_([a-z])/g, (g) => g[1].toUpperCase());
+}
+//# sourceMappingURL=grpc-to-http.js.map

package/dist/src/grpc-to-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc-to-http.js","sourceRoot":"","sources":["../../src/grpc-to-http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,OAAO,MAAM,UAAU,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,uDAAuD;IACvD,KAAK,EAAE,KAAK;CACf,CAAA;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACrC,CAAC;CACJ;AAUD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC7B,QAAgB,EAChB,SAAuB,EACvB,MAAwB,EACxB,OAAmB,EACnB,KAAQ;IAER,IAAI,gBAAgB,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,IAAI,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAW,CAAC,CAAC,2BAA2B;IACzE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAe,CAAA,CAAC,sCAAsC;IAEtG,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;IACnD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAW,CAAA;IACzF,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;YAC7C,CAAC,CAAC,gDAAgD;YAClD,CAAC,CAAC,qEAAqE,CAAA;QAC3E,MAAM,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAA;IAC1C,CAAC;IACD,IAAI,OAAO,GAAG,OAAO,CAAC,UAAU,CAAW,CAAA;IAE3C,IAAI,WAAW,GAAkB,SAAS,CAAA;IAC1C,IAAI,WAAW,GAAkB,SAAS,CAAA;IAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC,CAAC,0DAA0D;QAClF,WAAW,GAAG,KAAK,CAAA;IACvB,CAAC;SAAM,CAAC;QACJ,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,OAAO,GAAG,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC9C,CAAC;aAAM,CAAC;YACJ,WAAW,GAAG,KAAK,CAAA;QACvB,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IACzC,IAAI,gBAAgB,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,IAAI,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC,CAAA;IAChI,CAAC;IAED,MAAM,WAAW,GAAuB;QACpC,MAAM,EAAE,UAAU;QAClB,GAAG,EAAE,OAAO;QACZ,MAAM,EAAE,WAAW,EAAE,iDAAiD;QACtE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE,EAAE,gCAAgC;KAChE,CAAA;IAED,OAAO,KAAK,CAAC,OAAO,CAA0C,WAAW,CAAC,CAAA;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAmB,OAAe,EAAE,KAAQ;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IACxC,IAAI,MAAM,EAAE,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACrB,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;YACpC,IAAI,KAAK,GAAI,KAAiC,CAAC,SAAS,CAAC,CAAA;YAEzD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtB,uFAAuF;gBACvF,MAAM,YAAY,GAAG,WAAW,CAAC,SAAS,CAAC,CAAA;gBAC3C,KAAK,GAAI,KAAiC,CAAC,YAAY,CAAC,CAAA;YAC5D,CAAC;YAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,mBAAmB,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAA;YACpE,CAAC;YAED,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QAC7E,CAAC,CAAC,CAAA;IACN,CAAC;IACD,OAAO,OAAO,CAAA;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,SAAiB;IAClC,OAAO,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC,CAAA;AACrE,CAAC"}

package/index.ts

@@ -0,0 +1,2 @@
+export { executeGrpcToHttp, GrpcToHttpException, grpcToHttpConfig } from './src/grpc-to-http.js';
+export type { GrpcToHttpPromise } from './src/grpc-to-http.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@yylego/grpc-to-http",
+  "version": "0.0.1",
+  "description": "convert a TypeScript gRPC client into an HTTP client using Axios",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "LICENSE",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "type": "module",
+  "homepage": "https://github.com/yylego/grpc-to-http",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yylego/grpc-to-http.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yylego/grpc-to-http/issues"
+  },
+  "keywords": [
+    "protobuf-ts/plugin",
+    "Protocol Buffers",
+    "protobuf",
+    "TypeScript",
+    "protoc",
+    "gRPC-web",
+    "gRPC",
+    "grpc-to-http",
+    "axios"
+  ],
+  "author": "yylego",
+  "contributors": [
+    {
+      "name": "yyle88",
+      "url": "https://github.com/yyle88"
+    }
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@protobuf-ts/runtime-rpc": "^2.11.1",
+    "axios": "^1.13.6",
+    "url-join": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/grpc-to-http.ts

@@ -0,0 +1,142 @@
+import type {RpcTransport, RpcOptions, MethodInfo} from '@protobuf-ts/runtime-rpc'
+import axios from 'axios'
+import type {AxiosRequestConfig, AxiosResponse} from 'axios'
+import type {JsonObject} from '@protobuf-ts/runtime'
+import urlJoin from 'url-join';
+
+/**
+ * Configuration object for grpc-to-http.
+ * Modify these options to control package runtime settings.
+ */
+export const grpcToHttpConfig = {
+    /** Enable debug logging to console. Default: false. */
+    debug: false,
+}
+
+/**
+ * Custom exception class for grpc-to-http conversion failures.
+ * Allows callers to distinguish conversion exceptions from network exceptions via instanceof.
+ */
+export class GrpcToHttpException extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = 'GrpcToHttpException'
+    }
+}
+
+/**
+ * Represents a promise that resolves to an Axios response containing the output-resp object.
+ *
+ * @template I - The type of the input-param object.
+ * @template O - The type of the output-resp object.
+ */
+export type GrpcToHttpPromise<I, O> = Promise<AxiosResponse<O, AxiosRequestConfig<I>>>
+
+/**
+ * Performs a gRPC call over HTTP using the specified transport mechanism, method information, and provided options.
+ * Returns a promise that resolves to the Axios response containing the output-resp object.
+ *
+ * @template I - The type of the input-param object.
+ * @template O - The type of the output-resp object.
+ * @param callType - The type of the gRPC call (e.g., unary, server streaming).
+ * @param transport - The transport mechanism for the gRPC call.
+ * @param method - The method information for the gRPC call.
+ * @param options - The options for the gRPC call, including the base URL and metadata.
+ * @param input - The input-param object containing the request data.
+ * @returns A promise that resolves to the Axios response containing the output-resp object.
+ * @throws Will throw an error if the HTTP method is not defined or if a required parameter is missing.
+ */
+export function executeGrpcToHttp<I extends object, O extends object>(
+    callType: string,
+    transport: RpcTransport,
+    method: MethodInfo<I, O>,
+    options: RpcOptions,
+    input: I,
+): GrpcToHttpPromise<I, O> {
+    if (grpcToHttpConfig.debug) {
+        console.debug(`[grpc-to-http] method=${method.name} params=${JSON.stringify(input)}`)
+    }
+
+    const baseUrl = options['baseUrl'] as string; // base URL from RpcOptions
+    const apiHttp = method.options['google.api.http'] as JsonObject // HTTP mapping from proto annotations
+
+    const reqMethods = ['get', 'post', 'put', 'delete']
+    const httpMethod = Object.keys(apiHttp).find((key) => reqMethods.includes(key)) as string
+    if (!httpMethod) {
+        const message = Object.keys(apiHttp).length === 0
+            ? 'Request error - No HTTP method defined in GRPC'
+            : 'Request error - Non GET/POST/PUT/DELETE HTTP method defined in GRPC'
+        throw new GrpcToHttpException(message)
+    }
+    let uriPath = apiHttp[httpMethod] as string
+
+    let queryParams: I | undefined = undefined
+    let requestBody: I | undefined = undefined
+    if (apiHttp.body === '*') { // when body is '*', send the entire input as request body
+        requestBody = input
+    } else {
+        if (uriPath.includes('{') && uriPath.includes('}')) {
+            uriPath = rewritePathParam(uriPath, input)
+        } else {
+            queryParams = input
+        }
+    }
+    const fullUrl = urlJoin(baseUrl, uriPath)
+    if (grpcToHttpConfig.debug) {
+        console.debug(`[grpc-to-http] method=${method.name} params=${JSON.stringify(input)} ${httpMethod.toUpperCase()} ${fullUrl}`)
+    }
+
+    const axiosConfig: AxiosRequestConfig = {
+        method: httpMethod,
+        url: fullUrl,
+        params: queryParams, // passed as URL query string (e.g. GET requests)
+        data: requestBody,
+        headers: options.meta ?? {}, // pass metadata as HTTP headers
+    }
+
+    return axios.request<O, AxiosResponse<O, AxiosRequestConfig>>(axiosConfig)
+}
+
+/**
+ * Rewrites the URI path by replacing path parameters with corresponding values from the input-param object.
+ * If a parameter is not found in the input-param object, it attempts to convert the parameter name from snake_case to camelCase.
+ *
+ * @template T - The type of the input-param object.
+ * @param uriPath - The URI path containing parameters in the format `{param}`.
+ * @param input - The input-param object containing values for the parameters.
+ * @returns The URI path with parameters replaced by their corresponding values from the input-param object.
+ * @throws Will throw an error if a parameter is missing in the input-param object.
+ */
+function rewritePathParam<T extends object>(uriPath: string, input: T): string {
+    const params = uriPath.match(/{(\w+)}/g)
+    if (params) {
+        params.forEach((param) => {
+            const paramName = param.slice(1, -1)
+            let value = (input as Record<string, unknown>)[paramName]
+
+            if (value === undefined) {
+                // try converting snake_case to camelCase (e.g. example_param_name -> exampleParamName)
+                const newParamName = toCamelCase(paramName)
+                value = (input as Record<string, unknown>)[newParamName]
+            }
+
+            if (value === undefined) {
+                throw new GrpcToHttpException(`MISSING PARAMETER: ${paramName}`)
+            }
+
+            uriPath = uriPath.replace(param, encodeURIComponent(String(value ?? '')))
+        })
+    }
+    return uriPath
+}
+
+/**
+ * Converts a snake_case string to camelCase.
+ * For example, `example_param_name` will be converted to `exampleParamName`.
+ *
+ * @param paramName - The snake_case string to be converted.
+ * @returns The converted camelCase string.
+ */
+function toCamelCase(paramName: string): string {
+    return paramName.replace(/_([a-z])/g, (g) => g[1]!.toUpperCase())
+}