{"id":16378081,"url":"https://github.com/lemmotresto/gateway.ts","last_synced_at":"2026-06-21T02:31:58.209Z","repository":{"id":186811156,"uuid":"674636728","full_name":"LemmoTresto/gateway.ts","owner":"LemmoTresto","description":"A simple gateway for your microservices","archived":false,"fork":false,"pushed_at":"2023-08-26T11:46:19.000Z","size":92,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-11T02:33:57.320Z","etag":null,"topics":["api","gateway","http","microservices"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LemmoTresto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-08-04T12:33:08.000Z","updated_at":"2025-09-10T11:25:35.000Z","dependencies_parsed_at":"2024-11-08T16:44:35.640Z","dependency_job_id":"afab964a-eaa9-499f-aa50-2660ebe7e3e7","html_url":"https://github.com/LemmoTresto/gateway.ts","commit_stats":null,"previous_names":["lemmotresto/gateway.ts"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/LemmoTresto/gateway.ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemmoTresto%2Fgateway.ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemmoTresto%2Fgateway.ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemmoTresto%2Fgateway.ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemmoTresto%2Fgateway.ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LemmoTresto","download_url":"https://codeload.github.com/LemmoTresto/gateway.ts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemmoTresto%2Fgateway.ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34592050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"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":["api","gateway","http","microservices"],"created_at":"2024-10-11T03:44:33.956Z","updated_at":"2026-06-21T02:31:58.189Z","avatar_url":"https://github.com/LemmoTresto.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gateway.ts\n![npm](https://img.shields.io/npm/v/gateway.ts?style=for-the-badge\u0026logo=npm)\n![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/LemmoTresto/gateway.ts/release.yml?style=for-the-badge\u0026logo=github)\n\n\n\n## A simple gateway for your microservices.\n\n### Installation\n\n```bash\nnpm install gateway.ts # Optionally save as a dev dependency\n```\n\n### Usage\n\nThis is a use case for a Cloudflare Worker. The same principles apply to other environments/projects.\n\nYou first want to retrieve a `GatewayBuilder` via the `Gateway.builder` method. \nThis method takes 3 optional generic types:\n`RequestType`, `ResponseType` and `Args`.\n\nThese are used to define the types of the request, response and any optional arguments that are passed to the **Matchers**, **Origins** and **Policies**.\n\nIn this case these are `Request`, `Response` and `[Env]` respectively.\n\nAfter this you can define your routes and global policies, like shown below.\n\n```typescript\nimport { Gateway, Route } from 'gateway.ts';\nimport { SubdomainMatcher } from \"gateway.ts/matchers\";\nimport { UrlOrigin } from \"gateway.ts/origins\";\n\nconst gateway = Gateway.builder\u003cRequest, Response, [Env]\u003e()\n\t.setDefaultOrigin(new UrlOrigin()) // This is the default origin, used when no other origins match. This is optional and will default to UrlOrigin.\n\t.setRoutes([\n\t\tnew Route({\n\t\t\tmatcher: new SubdomainMatcher({ subdomain: \"auth.api\" }),\n\t\t\torigin: new BindingOrigin({ binding: \"AUTH_API\" }),\n            // As you can see we don't use policies here as they are optional.\n\t\t}),\n\t\tnew Route({\n\t\t\tmatcher: new SubdomainMatcher({ subdomain: \"replay.api\" }),\n\t\t\torigin: new BindingOrigin({ binding: \"REPLAY_PARSER_API\" }),\n\t\t\tpolicies: {\n\t\t\t\trequest: [new AuthenticationPolicy()],\n\t\t\t\tresponse: [new CorsPolicy()]\n\t\t\t}\n\t\t}),\n\t])\n\t.setGlobalPolicies({\n\t\trequest: [new AuthenticationPolicy()]\n\t})\n\t.build();\n```\n\nAfter this you can use the `gateway.handle` method to handle requests. You can hook this up to any environment/framework you want.\n\nThis is an example for a Cloudflare Worker:\n\n```typescript\nexport default {\n    async fetch(\n        request: Request,\n        env: Env,\n        ctx: ExecutionContext\n    ): Promise\u003cResponse\u003e {\n        return await gateway.handle(request, env);\n    },\n};\n````\n\n### Concepts\n\nIn this section we will go over the concepts used in this library.\nAll concepts have the RequestType, ResponseType and Args generic types, these are not required.\nHowever, if you use custom types in your Gateway and you have unexpected errors without the generic types filled in your custom classes I suggest adding them.\n\n#### Matchers\n\nMatchers are used to determine which route to use for a given request. They are matched in parallel and the first one to match is used.\nYou can create your own Matchers by extending the `Matcher` abstract class.\n\nAn example is shown here:\n\n```typescript\nexport class SubdomainMatcher extends Matcher\u003c{ subdomain: string; }\u003e {\n    async match(request: IRequest): Promise\u003cboolean\u003e {\n        const url = new URL(request.url);\n        return url.hostname.startsWith(this.options.subdomain)\n    }\n}\n```\n\nThe `Matcher` class has a few generic types that can be used to pass options to the matcher and to define the request, response and args types.\n\n\n#### Origins\n\nOrigins are used to determine where to route a request. These are optional and if none are provided the request will be routed to the original destination.\nYou can create your own Origins by extending the `Origin` abstract class.\n\nAn example is shown here:\n\n```typescript\nexport class BindingOrigin extends Origin\u003c{ binding: string; }, Request, Response, [Env]\u003e {\n    async execute(request: Request, env: Env): Promise\u003cResponse\u003e {\n        const binding: Fetcher = env[this.options.binding];\n        return await binding.fetch(request)\n    }\n}\n```\n\nThe `Origin` class has a few generic types that can be used to pass options to the origin and to define the request, response and args types.\n\n#### Policies\n\nPolicies are used to modify the request and response. These are optional and if none are provided the request and response will be passed through unmodified.\n\nThere are two types of policies: `RequestPolicy` and `ResponsePolicy`.\n\nA RequestPolicy is used to modify the request before it is sent to the origin. It can return either a modified request or a response in case you want to abort the origin call.\nTo return a request or response you can use the `PolicyResult.request` and `PolicyResult.response` methods respectively.\n\nAn example is shown here:\n\n```typescript\nexport class AuthenticationPolicy extends RequestPolicy\u003c{ test: string; }, Request, Response, [Env]\u003e {\n    async transform(request: Request, env: Env): Promise\u003cPolicyResult\u003cRequest, Response\u003e\u003e {\n        if (!request.headers.has('Authorization')) return PolicyResult.response(new Response('Not Authorized.', { status: 403 }))\n\n        const authHeader = request.headers.get('Authorization');\n        \n        // Do something with authHeader and your test option.\n\n        return PolicyResult.request(request);\n    }\n}\n```\n\nA ResponsePolicy is used to modify the response before it is sent to the client.\n\nAn example is shown here:\n\n```typescript\nexport class CorsPolicy extends ResponsePolicy\u003c{ origin: string, methods: string[], headers: string[] }, Response\u003e {\n    async transform(response: Response): Promise\u003cResponse\u003e {\n        return PolicyResult.response\u003cResponse\u003e(new Response(response.body, {\n            ...response,\n            headers: {\n                ...response.headers,\n                'Access-Control-Allow-Origin': this.options.origin,\n                'Access-Control-Allow-Methods': this.options.methods.join(', '),\n                'Access-Control-Allow-Headers': this.options.headers.join(', ')\n            }\n        }));\n    }\n}\n```\n\nThe `RequestPolicy` and `ResponsePolicy` classes have a few generic types that can be used to pass options to the policy and to define the request, response and args types.\n\n### Contributing\n\nIf you want to contribute to this project feel free to open a pull request or issue.\n\n### License\n\nThis project is licensed under the GNU LESSER GENERAL PUBLIC license. Read the LICENSE file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemmotresto%2Fgateway.ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flemmotresto%2Fgateway.ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemmotresto%2Fgateway.ts/lists"}