{"id":31786010,"url":"https://github.com/chicunic/node-grpc-rest-demo","last_synced_at":"2025-10-10T12:29:22.258Z","repository":{"id":317128547,"uuid":"1063058462","full_name":"chicunic/node-grpc-rest-demo","owner":"chicunic","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-29T02:01:05.000Z","size":132,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T03:26:41.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chicunic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T05:40:52.000Z","updated_at":"2025-09-29T02:01:08.000Z","dependencies_parsed_at":"2025-09-29T03:26:59.857Z","dependency_job_id":"81fa89f5-eece-4012-8103-26651a0e31bf","html_url":"https://github.com/chicunic/node-grpc-rest-demo","commit_stats":null,"previous_names":["chicunic/node-grpc-rest-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chicunic/node-grpc-rest-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chicunic%2Fnode-grpc-rest-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chicunic%2Fnode-grpc-rest-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chicunic%2Fnode-grpc-rest-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chicunic%2Fnode-grpc-rest-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chicunic","download_url":"https://codeload.github.com/chicunic/node-grpc-rest-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chicunic%2Fnode-grpc-rest-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003901,"owners_count":26083641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T12:29:20.782Z","updated_at":"2025-10-10T12:29:22.249Z","avatar_url":"https://github.com/chicunic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node.js gRPC/REST API Template\n\nA modern Node.js template for building APIs with both gRPC and REST support, optimized for Google Cloud Platform deployment. This template provides a solid foundation for creating scalable microservices with TypeScript, Express, and gRPC.\n\n## Features\n\n- **Dual Protocol Support**: Both REST API and gRPC endpoints\n- **Google Cloud Optimized**: Ready for Cloud Run deployment with Cloud Build CI/CD\n- **In-Memory Storage**: Fast in-memory data storage for development and testing\n- **TypeScript**: Full type safety and modern JavaScript features\n- **OpenAPI/Swagger**: Interactive API documentation\n- **gRPC Reflection**: Easy testing with grpcurl\n- **Health Checks**: Built-in health check endpoints for both protocols\n- **Testing**: Jest test suite with examples\n- **Code Quality**: ESLint, Prettier, and pre-commit hooks\n- **Docker Support**: Multi-stage production-ready Dockerfile\n- **Environment Configuration**: dotenv for configuration management\n- **Security**: Non-root container execution and proper signal handling\n\n## Prerequisites\n\n- Node.js \u003e= 22\n- pnpm (recommended) or npm\n\n## Quick Start\n\n1. **Clone the repository**\n\n```bash\ngit clone \u003crepository-url\u003e\ncd node-grpc-rest-demo\n```\n\n2. **Install dependencies**\n\n```bash\npnpm install\n```\n\n3. **Set up environment variables**\n\n```bash\ncp .env.example .env\n```\n\n4. **Run in development mode**\n\nREST API:\n\n```bash\npnpm run dev\n```\n\ngRPC Server:\n\n```bash\npnpm run dev:grpc\n```\n\n## Project Structure\n\n```\n├── proto/              # Protocol buffer definitions\n├── src/\n│   ├── config/        # Configuration files\n│   ├── grpc/          # gRPC server and handlers\n│   │   ├── handlers/  # gRPC service implementations\n│   │   ├── validators/ # gRPC request validators\n│   │   └── server.ts  # gRPC server setup\n│   ├── routes/        # REST API routes\n│   ├── services/      # Business logic layer\n│   ├── types/         # TypeScript type definitions\n│   ├── utils/         # Utility functions\n│   └── index.ts       # REST API entry point\n├── tests/             # Test files\n│   ├── specs/\n│   │   ├── integration/ # Integration tests\n│   │   ├── unit/       # Unit tests\n│   │   └── validator/  # Validator tests\n│   └── utils/         # Test utilities\n├── swagger.json       # OpenAPI specification\n└── package.json       # Dependencies and scripts\n```\n\n## Available Scripts\n\n- `pnpm run build` - Build the TypeScript project\n- `pnpm run start` - Start the REST API server\n- `pnpm run start:grpc` - Start the gRPC server\n- `pnpm run dev` - Run REST API in development mode with hot reload\n- `pnpm run dev:grpc` - Run gRPC server in development mode\n- `pnpm run test` - Run test suite\n- `pnpm run test:coverage` - Run tests with coverage report\n- `pnpm run test:integration` - Run integration tests only\n- `pnpm run lint` - Run ESLint\n- `pnpm run format` - Check code formatting\n- `pnpm run typecheck` - Run TypeScript type checking\n- `pnpm run check` - Run all checks (typecheck, lint, format)\n- `pnpm run fix` - Auto-fix code issues\n\n## API Documentation\n\n### REST API\n\nWhen running in development mode, Swagger UI is available at:\n\n```\nhttp://localhost:8080/api-docs\n```\n\n### gRPC\n\nThe gRPC server supports reflection for easy testing with grpcurl:\n\n```bash\n# List available services\ngrpcurl -plaintext localhost:8080 list\n\n# Describe a service\ngrpcurl -plaintext localhost:8080 describe example.UserService\n\n# Call a gRPC method\ngrpcurl -plaintext -d '{\"id\":\"1\"}' localhost:8080 example.UserService/GetUser\n```\n\n## Example Services\n\nThe template includes two example services to demonstrate the structure:\n\n### User Service\n\n- CRUD operations for user management\n- REST endpoints: `/api/v1/users`\n- gRPC service: `UserService`\n- Input validation using class-validator\n- Pagination support\n\n### Product Service\n\n- Product search and management\n- REST endpoints: `/api/v1/products`\n- gRPC service: `ProductService`\n- Input validation using class-validator\n- Search by category and price range\n- Pagination support\n\n## Testing\n\nThe project includes three types of tests:\n\n### Unit Tests\n\nLocated in `tests/specs/unit/`, testing isolated services and utility functions.\n\n### Integration Tests\n\nLocated in `tests/specs/integration/`, testing complete API endpoints:\n\n- `*.grpc.integration.test.ts` - gRPC service integration tests\n- `*.rest.integration.test.ts` - REST API integration tests\n\n### Validator Tests\n\nLocated in `tests/specs/validator/`, testing input validation logic:\n\n- `*.grpc.validator.test.ts` - gRPC request validator tests\n- `*.rest.validator.test.ts` - REST API validator tests\n\nRun the test suite:\n\n```bash\npnpm run test\n```\n\nRun with coverage:\n\n```bash\npnpm run test:coverage\n```\n\nRun integration tests only:\n\n```bash\npnpm run test:integration\n```\n\n## Docker\n\nBuild the Docker image:\n\n```bash\ndocker build -t node-grpc-rest-demo .\n```\n\nRun the container:\n\n```bash\ndocker run -p 8080:8080 node-grpc-rest-demo\n```\n\n## Google Cloud Platform Deployment\n\n### Prerequisites\n\n- Google Cloud Project with billing enabled\n- Cloud Build and Cloud Run APIs enabled\n- gcloud CLI installed and configured\n\n### Deployment Configuration\n\nThe project includes optimized configurations for GCP deployment:\n\n- `deployment/staging.json` - Staging environment configuration\n- `deployment/production.json` - Production environment configuration\n- `cloudbuild.yaml` - Automated CI/CD pipeline for Cloud Build\n- `Dockerfile` - Multi-stage build optimized for Cloud Run\n\n### Branch Strategy\n\n- **main**: Development branch\n- **staging**: Automatically deploys to staging environment\n- **production**: Automatically deploys to production environment\n\n### Manual Deployment\n\n```bash\n# Deploy to Cloud Run (REST API)\ngcloud run deploy node-grpc-rest-demo \\\n  --source . \\\n  --region us-central1 \\\n  --platform managed\n\n# Deploy gRPC service\ngcloud run deploy node-grpc-rest-demo-grpc \\\n  --source . \\\n  --region us-central1 \\\n  --platform managed \\\n  --use-http2 \\\n  --command pnpm \\\n  --args start:grpc\n```\n\n### Automated Deployment with Cloud Build\n\n1. **Connect your repository to Cloud Build**:\n\n```bash\ngcloud builds repositories create node-grpc-rest-demo \\\n  --remote-uri=https://github.com/your-org/node-grpc-rest-demo.git \\\n  --connection=your-connection-name \\\n  --region=us-central1\n```\n\n2. **Create Cloud Build triggers**:\n\n```bash\n# Staging trigger\ngcloud builds triggers create github \\\n  --repo-name=node-grpc-rest-demo \\\n  --branch-pattern=\"^staging$\" \\\n  --build-config=cloudbuild.yaml\n\n# Production trigger\ngcloud builds triggers create github \\\n  --repo-name=node-grpc-rest-demo \\\n  --branch-pattern=\"^production$\" \\\n  --build-config=cloudbuild.yaml\n```\n\n3. **Deploy by pushing to branch**:\n\n```bash\n# Deploy to staging\ngit checkout staging\ngit merge main\ngit push origin staging\n\n# Deploy to production\ngit checkout production\ngit merge staging\ngit push origin production\n```\n\n### GCP Features Utilized\n\n- **Cloud Run**: Serverless container hosting with automatic scaling\n- **Cloud Build**: CI/CD pipeline for automated deployments\n- **Container Registry**: Docker image storage\n- **Cloud Logging**: Centralized application logs\n- **Health Checks**: Startup and liveness probes for reliability\n- **HTTP/2 \u0026 gRPC**: Full protocol support for modern APIs\n\n## Configuration\n\nEnvironment variables can be configured in the `.env` file:\n\n### Core Configuration\n\n- `PORT` - Server port (default: 8080)\n- `NODE_ENV` - Environment (development/production)\n- `LOG_LEVEL` - Logging level (default: info)\n\n## Data Storage\n\n### In-Memory Storage\n\nThis template uses in-memory storage for data persistence. All data is stored in JavaScript Map objects for fast access:\n\n```typescript\n// Create and store data in memory\nconst user = await userService.createUser({\n  username: 'john_doe',\n  email: 'john@example.com',\n  fullName: 'John Doe',\n});\n```\n\n**Note**: All data will be lost when the application restarts. This is ideal for development, testing, and prototyping. For production use, consider integrating a persistent database solution.\n\n## Adding New Services\n\n1. Define your proto messages in `proto/`\n2. Create service implementation in `src/services/`\n3. Add REST routes in `src/routes/`\n4. Implement gRPC handlers in `src/grpc/handlers/`\n5. Create gRPC validators in `src/grpc/validators/` (using class-validator)\n6. Update Swagger documentation in `swagger.json`\n7. Add corresponding tests:\n   - Unit tests in `tests/specs/unit/`\n   - Integration tests in `tests/specs/integration/`\n   - Validator tests in `tests/specs/validator/`\n8. Services use fast in-memory storage\n\n## Development Tools\n\n- **Type checking**: `pnpm run typecheck`\n- **Linting**: `pnpm run lint`\n- **Lint with auto-fix**: `pnpm run lint:fix`\n- **Format check**: `pnpm run format`\n- **Code formatting**: `pnpm run format:fix`\n- **Full quality check**: `pnpm run check` (runs typecheck, lint, and format check)\n- **Auto-fix all issues**: `pnpm run fix` (runs lint:fix and format:fix)\n\n## Git Hooks\n\nGit hooks are automatically configured when you run `pnpm install`. They ensure code quality before commits and pushes.\n\n## Tech Stack\n\n- **Runtime**: Node.js 22+ (Alpine Linux in production)\n- **Language**: TypeScript\n- **Frameworks**: Express.js (REST), gRPC\n- **Validation**: class-validator, express-openapi-validator\n- **Storage**: In-memory storage with JavaScript Map\n- **Cloud Platform**: Google Cloud Platform (Cloud Run, Cloud Build)\n- **Testing**: Jest\n- **Code Quality**: ESLint, Prettier\n- **Package Manager**: pnpm\n- **Container**: Docker with multi-stage builds\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchicunic%2Fnode-grpc-rest-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchicunic%2Fnode-grpc-rest-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchicunic%2Fnode-grpc-rest-demo/lists"}