{"id":24203290,"url":"https://github.com/mahabubx7/terry","last_synced_at":"2026-04-13T03:01:48.729Z","repository":{"id":271869659,"uuid":"914813275","full_name":"mahabubx7/terry","owner":"mahabubx7","description":"Terry =\u003e Typescript + Express.js + Openapi-TS based boilerplate/custom-framework","archived":false,"fork":false,"pushed_at":"2025-01-10T12:24:07.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-10T12:32:57.428Z","etag":null,"topics":["express","nodejs","openapi","redoc","scalar-docs","swagger","typescript"],"latest_commit_sha":null,"homepage":"https://terry-42pl.onrender.com","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/mahabubx7.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}},"created_at":"2025-01-10T11:05:47.000Z","updated_at":"2025-01-10T12:22:35.000Z","dependencies_parsed_at":"2025-01-10T12:33:06.986Z","dependency_job_id":"521fbc25-424a-46a3-b02a-bf5f7780617d","html_url":"https://github.com/mahabubx7/terry","commit_stats":null,"previous_names":["mahabubx7/terry"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahabubx7%2Fterry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahabubx7%2Fterry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahabubx7%2Fterry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahabubx7%2Fterry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mahabubx7","download_url":"https://codeload.github.com/mahabubx7/terry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241654715,"owners_count":19997914,"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","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":["express","nodejs","openapi","redoc","scalar-docs","swagger","typescript"],"created_at":"2025-01-13T22:21:43.763Z","updated_at":"2026-04-13T03:01:43.708Z","avatar_url":"https://github.com/mahabubx7.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terry\n\nA batteries-included Express.js framework with automatic OpenAPI documentation generation, request/response validation, API versioning, and response serialization.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- 🚀 Express.js based REST API framework\n- 📚 Automatic OpenAPI/Swagger documentation generation\n- ✅ Request/Response validation using Zod\n- 🔄 Auto-loading of route modules\n- 🛡️ Built-in security with Helmet\n- 🌐 CORS support\n- 🎯 TypeScript support\n- 🔢 Built-in API versioning (v1)\n- 📖 Multiple API documentation UIs (Swagger, ReDoc, Scalar)\n- 🔥 Hot-reload in development\n- 🏭 Production-ready build setup\n- 🔍 Response serialization and transformation\n- ⚙️ Automatic environment configuration\n\n## Response Serialization\n\nTerry includes automatic response serialization and transformation. Each response schema acts as a transformer:\n\n```typescript\n// schema.ts\nimport { z } from 'zod';\n\nexport const HealthCheckResponse = z.object({\n  status: z.enum(['ok', 'error']),\n  uptime: z.number(),\n  memory: z.object({\n    used: z.number(),\n    total: z.number(),\n  }),\n}).openapi('HealthCheckResponse');\n\n// routes.ts\n{\n  method: 'get',\n  path: '/',\n  schema: {\n    response: HealthCheckResponse,\n  },\n  handler: async (req, res) =\u003e {\n    // This will be validated against HealthCheckResponse schema\n    return {\n      status: 'ok',           // Must be 'ok' or 'error'\n      uptime: process.uptime(),\n      memory: {\n        used: 100,\n        total: 1000,\n      }\n    };\n  }\n}\n\n// Invalid responses will throw 422 Unprocessable Entity\nreturn {\n  status: 'unknown',  // Error: Invalid enum value\n  uptime: 'invalid'   // Error: Expected number, received string\n};\n```\n\n## Environment Configuration\n\nTerry automatically loads environment variables from `.env` file and validates them using Zod:\n\n```typescript\n// config/env.ts\nimport { z } from 'zod';\n\nconst envSchema = z.object({\n  PORT: z.string().transform(Number).default('3456'),\n  NODE_ENV: z.enum(['development', 'production', 'test']),\n  API_PREFIX: z.string().default('/api'),\n  // ... other validations\n});\n\n// Usage in your code\nimport env from '../config/env';\napp.listen(env.PORT);\n```\n\nCreate a `.env` file based on `.env.example`:\n\n```env\n# Server\nPORT=3456\nNODE_ENV=development\n\n# API\nAPI_PREFIX=/api\n\n# Documentation\nDOCS_ENABLED=true\n\n# Security\nCORS_ORIGIN=*\nRATE_LIMIT_WINDOW=15\nRATE_LIMIT_MAX=100\n\n# Logging\nLOG_LEVEL=debug\nPRETTY_LOGGING=true\n```\n\n## Project Structure\n\n```\nsrc/\n├── app/                    # Application modules\n│   ├── users/             # User module example\n│   │   ├── users.routes.ts # Route definitions\n│   │   └── users.schema.ts # Zod schemas\n│   ├── todos/             # Todo module example\n│   │   ├── todos.routes.ts\n│   │   └── todos.schema.ts\n│   └── health/            # Health check module\n│       ├── health.routes.ts\n│       └── health.schema.ts\n├── lib/                   # Framework core\n│   ├── openapi.ts        # OpenAPI configuration\n│   └── router.ts         # Route builder\n├── config/               # Configuration\n│   ├── env.ts           # Environment variables\n│   └── logger.ts        # Logging configuration\n└── main.ts              # Application entry point\n```\n\n## Module Structure\n\nEach module should follow this structure:\n\n1. `*.routes.ts` - Route definitions with handlers\n```typescript\nimport { ModuleRoutes } from '../../lib/openapi';\nimport { MySchema } from './my.schema';\n\nconst routes: ModuleRoutes = [\n  {\n    method: 'get',\n    path: '/',\n    schema: {\n      response: MySchema,\n    },\n    handler: async (req, res) =\u003e {\n      // Your handler logic\n      return { data: 'example' };\n    },\n    summary: 'List items',\n    description: 'Get a list of items',\n    tags: ['MyModule']\n  }\n];\n\nmodule.exports = routes;\nmodule.exports.default = routes;\n```\n\n2. `*.schema.ts` - Zod schemas for validation\n```typescript\nimport { z } from 'zod';\n\nexport const MySchema = z.object({\n  id: z.string().uuid(),\n  name: z.string(),\n}).openapi('MySchema');\n```\n\n## Environment Modes\n\n### Development Mode\n- Uses TypeScript files directly\n- Hot-reload enabled\n- Detailed error logging\n- Pretty-printed logs\n- Source maps enabled\n\n```bash\nnpm run dev\n```\n\n### Production Mode\n- Uses compiled JavaScript\n- Optimized for performance\n- Minimal error logging\n- JSON formatted logs\n- No source maps\n\n```bash\nnpm run build\nnpm run start:prod\n```\n\n## API Documentation\n\nThe framework automatically generates OpenAPI documentation from your route definitions and schemas. Access the documentation at:\n\n- Swagger UI: `http://localhost:3456/api/docs/swagger`\n- ReDoc: `http://localhost:3456/api/docs/redoc`\n- Scalar: `http://localhost:3456/api/docs/scalar`\n- OpenAPI JSON: `http://localhost:3456/api/docs/api.json`\n\n## Docker Support\n\n### Production\n```bash\ndocker compose build api\ndocker compose up api\n```\n\n### Development with Hot-Reload\n```bash\ndocker compose --profile dev up api-dev\n```\n\n## Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# Server\nPORT=3456\nNODE_ENV=development\n\n# API\nAPI_PREFIX=/api\n\n# Documentation\nDOCS_ENABLED=true\n\n# Security\nCORS_ORIGIN=*\nRATE_LIMIT_WINDOW=15\nRATE_LIMIT_MAX=100\n\n# Logging\nLOG_LEVEL=debug\nPRETTY_LOGGING=true\n```\n\n## Scripts\n\n- `npm run dev`: Start development server with hot-reload\n- `npm run build`: Build for production\n- `npm run start:prod`: Start production server\n- `npm run lint`: Run linter\n- `npm run format`: Format code\n- `npm run clean`: Clean build directory\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a new Pull Request\n\n## License\n\nTerry is open-source software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n\nCopyright (c) 2024 Cursor Inc. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahabubx7%2Fterry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahabubx7%2Fterry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahabubx7%2Fterry/lists"}