{"id":26432297,"url":"https://github.com/yoaquim/zemi","last_synced_at":"2025-10-04T10:54:00.504Z","repository":{"id":46985833,"uuid":"512997745","full_name":"yoaquim/zemi","owner":"yoaquim","description":"zemi is a data-driven and reverse-routing library for Express JS.","archived":false,"fork":false,"pushed_at":"2024-12-18T06:56:08.000Z","size":1044,"stargazers_count":6,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-17T08:48:45.508Z","etag":null,"topics":["api","data-driven","express","expressjs","middleware","nodejs","rest","reverse-routes","router","routing"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/zemi","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yoaquim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2022-07-12T04:26:47.000Z","updated_at":"2023-11-13T16:03:31.000Z","dependencies_parsed_at":"2024-09-18T14:14:28.385Z","dependency_job_id":"14b11f95-3c52-4a85-8d6f-342a7d7c5010","html_url":"https://github.com/yoaquim/zemi","commit_stats":{"total_commits":110,"total_committers":1,"mean_commits":110.0,"dds":0.0,"last_synced_commit":"0e3e947706ecba3488a95d26ba054f20d04abe31"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoaquim%2Fzemi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoaquim%2Fzemi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoaquim%2Fzemi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoaquim%2Fzemi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yoaquim","download_url":"https://codeload.github.com/yoaquim/zemi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244050751,"owners_count":20389766,"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":["api","data-driven","express","expressjs","middleware","nodejs","rest","reverse-routes","router","routing"],"created_at":"2025-03-18T06:17:46.842Z","updated_at":"2025-10-04T10:53:55.483Z","avatar_url":"https://github.com/yoaquim.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zemi\n\n[![build](https://github.com/yoaquim/zemi/actions/workflows/ci.yml/badge.svg)](https://github.com/yoaquim/zemi/actions/workflows/ci.yml)\n[![Code Climate Coverage](https://codeclimate.com/github/yoaquim/zemi/badges/coverage.svg)](https://codeclimate.com/github/yoaquim/zemi/coverage)\n[![Code Climate Maintainability](https://codeclimate.com/github/yoaquim/zemi/badges/gpa.svg)](https://codeclimate.com/github/yoaquim/zemi)\n[![Snyk.io Vulnerabilities](https://snyk.io/test/github/yoaquim/zemi/badge.svg?targetFile=package.json)](https://snyk.io/test/github/yoaquim/zemi?targetFile=package.json)\n\n[![npm Version](https://img.shields.io/npm/v/zemi?color=137dc2\u0026logo=npm)](https://www.npmjs.com/package/zemi)\n[![Types](https://badgen.net/npm/types/zemi)](https://github.com/yoaquim/zemi/tree/main/src/types)\n[![Dependencies](https://img.shields.io/badge/dependencies-2-blue)](https://github.com/yoaquim/zemi/blob/main/package.json#L27-L30)\n[![Install Size](https://packagephobia.com/badge?p=zemi)](https://packagephobia.com/result?p=zemi)\n[![License](https://badgen.net/npm/license/zemi)](https://github.com/yoaquim/zemi/blob/main/LICENSE.md)\n\n\u003cbr\u003e\n\nzemi is a [data-driven](#data-driven) routing library for [Express](https://expressjs.com/), built with Typescript.\n\nFeatures:\n\n- [reverse-routing](#reverse-routing)\n- [path-parameter inheritance](#parameter-inheritance)\n- route-level [middleware support](#middleware)\n\n\u003cbr\u003e\n\n# Table of Contents\n\n1. [Routing](#routing)\n    1. [Data-driven](#data-driven)\n    2. [Reverse-routing](#reverse-routing)\n    3. [Middleware](#middleware)\n    4. [Parameter Inheritance](#parameter-inheritance)\n2. [Types](#types)\n    1. [ZemiMethod](#zemimethod)\n    2. [ZemiRequestHandler](#zemirequesthandler)\n    3. [ZemiRequest](#zemirequest)\n    4. [ZemiResponse](#zemiresponse)\n    5. [ZemiRouteDefinition](#zemiroutedefinition)\n    6. [ZemiRoute](#zemiroute)\n3. [Examples](#examples)\n   1. [Simple](https://github.com/yoaquim/zemi/blob/main/examples/simple.ts)\n   2. [With Middleware](https://github.com/yoaquim/zemi/blob/main/examples/with-middleware.ts)\n   3. [Using Named Routes For Redirects](https://github.com/yoaquim/zemi/blob/main/examples/using-named-routes-for-redirect.ts)\n   4. [Using Reverse Routing](https://github.com/yoaquim/zemi/blob/main/examples/using-reverse-routing.ts)\n   5. [With Param Inheritance from Parent Routes](https://github.com/yoaquim/zemi/blob/main/examples/nested-route-param-inheritance.ts)\n4. [Limitations](#limitations)\n\n\u003cbr\u003e\n\n## Routing\n\n### Data-driven\n\nAssume you have the following functions defined: `petsHandler`, `dogBreedHandler`, `dogBreedsIdHandler`, `catsByIdHandler` ; e.g.:\n\n```ts\nconst petsHandler = (request: ZemiRequest, response: ZemiResponse) =\u003e {\n  // do something with this request and respond\n  response.status(200).json({ pets: [\"dogs\", \"cats\"] });\n};\n\nconst dogBreedHandler = (request: ZemiRequest, response: ZemiResponse) =\u003e {\n   //...\n};\n\nconst dogBreedsIdHandler = (request: ZemiRequest, response: ZemiResponse) =\u003e {\n   //...\n};\n\nconst catsByIdHandler = (request: ZemiRequest, response: ZemiResponse) =\u003e {\n   //...\n};\n```\n\nThen the following code:\n\n```ts\nimport express from \"express\";\nimport zemi, { ZemiRoute, ZemiMethod } from \"zemi\";\n\nconst { GET } = ZemiMethod;\n\nconst routes: Array\u003cZemiRoute\u003e = [\n  {\n    name: \"pets\",\n    path: \"/pets\",\n    [GET]: petsHandler,\n    routes: [\n      {\n        name: \"dogBreeds\",\n        path: \"/dogs/:breed\",\n        [GET]: dogBreedHandler,\n        routes: [\n          {\n            name: \"dogsByBreedById\",\n            path: \"/:id\",\n            [GET]: dogBreedsIdHandler\n          }\n        ]\n      },\n      {\n        name: \"catsById\",\n        path: \"/cats/:id\",\n        [GET]: catsByIdHandler\n      }\n    ]\n  }\n];\n\nconst app = express();\napp.use(express.json());\napp.use(\"/\", zemi(routes));\napp.listen(3000);\n```\n\nGenerates an API like:\n\n| routes                  | response                                            |\n|-------------------------|-----------------------------------------------------|\n| `/pets`                 | `{pets: ['dogs', 'cats', 'rabbits']}`               |\n| `/pets/dogs`            | `Cannot GET /pets/dogs/` (since it was not defined) |\n| `/pets/dogs/labrador`   | `{\"result\":[\"Fred\",\"Barney\",\"Wilma\"]}`              |\n| `/pets/dogs/labrador/1` | `{\"result\":\"Barney\"}`                               |\n| `/pets/cats`            | `Cannot GET /pets/cats/` (since it was not defined) |\n| `/pets/cats/2`          | `{\"result\":\"Daphne\"}`                               |\n\n\u003cbr\u003e\n\n### Reverse-routing\n\nzemi builds route-definitions for all routes and adds them to the [`ZemiRequest`](#zemirequest) passed to the handler function.\n\nAll route-definitions are named (index-accessible) and follow the same naming convention: `[ancestor route names]-[parent route name]-[route name]`, e.g. `basePath-greatGrandparent-grandparent-parent-myRoute`, `pets-dogsBreeds-dogsByBreedById`.\n\nEach route-definition contains the name, path, and path-parameters (if present) of the route.\nIt also contains a reverse function which — when invoked with an object mapping path-parameters to values — will return the interpolated path with values.\n\nE.g. a handler like this:\n\n```ts\nimport { ZemiRequest, ZemiResponse, ZemiRouteDefinition } from \"zemi\";\n\nconst petsHandler = (request: ZemiRequest, response: ZemiResponse) =\u003e {\n  const routeDefinitions: Record\u003cstring, ZemiRouteDefinition\u003e = request.routeDefinitions;\n  const { path, name, parameters, reverse } = routeDefinitions[\"pets-dogBreeds-dogsByBreedById\"];\n  response.status(200).json({ path, name, parameters, reverse: reverse({ breed: 'Corgi', id: '99' }) });\n};\n```\n\nReturns:\n\n```json\n  {\n  \"path\": \"/pets/dogs/:breed/:id\",\n  \"name\": \"pets-dogBreeds-dogsByBreedById\",\n  \"parameters\": [\n    \"breed\",\n    \"id\"\n  ],\n  \"reverse\": \"/pets/dogs/corgi/99\"\n}\n```\n\nThis allows you to generate links, redirect, and change path values without having to hardcode strings and change them later.\n\n\u003cbr\u003e\n\n### Middleware\n\nzemi lets you define middleware functions at the route level:\n\nRetaking and tweaking our example from the beginning:\n\n```ts\nimport { ZemiRequest, ZemiResponse } from \"zemi\";\nimport { NextFunction } from \"express\";\n\nconst routes: Array\u003cZemiRoute\u003e = [\n  {\n    name: \"pets\",\n    path: \"/pets\",\n    [GET]: petsHandler,\n    routes: [\n      {\n        name: \"dogBreeds\",\n        path: \"/dogs/:breed\",\n        [GET]: dogBreedHandler,\n        middleware: [\n          function logRouteDefs(request: ZemiRequest, response: ZemiResponse, next: NextFunction) {\n            console.log(JSON.stringify(request.routeDefinitions));\n            next();\n          }\n        ],\n        routes: [\n          {\n            name: \"dogsByBreedById\",\n            path: \"/:id\",\n            [GET]: dogBreedsIdHandler\n          }\n        ]\n      },\n      {\n        name: \"catsById\",\n        path: \"/cats/:id\",\n        [GET]: { handler: catsByIdHandler }\n      }\n    ]\n  }\n];\n```\n\nThe middleware function `logRouteDefs` defined at the `dogBreeds` level will be applied to all the methods at that level and all nested routes — which means our `dogsByBreedById` route will gain that functionality also.\n\n\u003cbr\u003e\n\n### Parameter Inheritance\n\nAs show in previous examples, parameters defined at parent routes are passed and available to nested routes.\n\nE.g. in this purposefully convoluted example:\n\n```ts\nconst routes: Array\u003cZemiRoute\u003e = [\n  {\n    name: \"pets\",\n    path: \"/pets\",\n    [GET]: petsHandler,\n    routes: [\n      {\n        name: \"dogBreeds\",\n        path: \"/dogs/:breed\",\n        [GET]: dogBreedHandler,\n        routes: [\n          {\n            name: \"dogsByBreedById\",\n            path: \"/:id\",\n            [GET]: dogBreedsIdHandler,\n            routes: [\n              {\n                name: \"dogsByBreedByIdDetailsSection\",\n                path: \"/details/:section\",\n                [GET]: dogBreedsIdDetailsSectionHandler,\n                routes: [\n                  {\n                    name: \"newDogsByBreedByIdDetailsSection\",\n                    path: \"/new\",\n                    [POST]: newDogsByBreedByIdDetailsSectionHandler\n                  }\n                ]\n              }\n            ]\n          }\n        ]\n      }\n    ]\n  }\n];\n```\n\nThe `newDogsByBreedByIdDetailsSection` route (path: `/pets/dogs/:breed/:id/details/:section/new`) will have `breed`, `id`, and `section` available as request parameters in the ZemiRequest object.\n\n\u003cbr\u003e\n\n## Types\n\n### `ZemiMethod`\n\n*Enum*\n\nThe HTTP methods supported by [`ZemiRoute`](#zemiroute).\n\n| Member    | Value     |\n|-----------|-----------|\n| `GET`     | `get`     |\n| `POST`    | `post`    |\n| `PUT`     | `put`     |\n| `DELETE`  | `delete`  |\n| `OPTIONS` | `options` |\n\n\u003cbr\u003e\n\n### `ZemiRequestHandler`\n\nHow to handle incoming requests for this route method; basically `express.RequestHandler`, but gets passed its own request and response versions, plus adds that routes [`ZemiRouteDefinition`](#zemiroutedefinition) as an optional fourth param.\n\n```ts\n(\n  request: ZemiRequest,\n  response: ZemiResponse,\n  next: express.NextFunction,\n  routeDef: ZemiRouteDefinition\n) =\u003e void\n```\n\n\u003cbr\u003e\n\n### `ZemiRequest`\n\n*extends `express.Request`*\n\nA wrapper for `express.Request`; adds `routeDefinitions` and `allowedResponseHttpCodes` to it.\n\n```ts\n{\n  routeDefinitions: Record\u003cstring, ZemiRouteDefinition\u003e;\n  // all other members from express.Request\n}\n\n```\n\n\u003cbr\u003e\n\n### `ZemiResponse`\n\n*extends `express.Response`*\n\nJust a wrapper for future-proofing; same as `express.Response`.\n\n\u003cbr\u003e\n\n### `ZemiRouteDefinition`\n\nRoute definition for a given [`ZemiRoute`](#zemiroute).\nContains the name, path, and path-parameters (if present) of the route it's defining.\nAlso provides a `reverse` function that, when invoked with an object that has parameter-values, will return the resolved path.\n\n```ts\n{\n  name: string;\n  path: string;\n  parameters: Array\u003cstring\u003e;\n  reverse: (parameterValues: object) =\u003e string;\n}\n```\n\n\u003cbr\u003e\n\n### `ZemiRoute`\n\nIt must be provided a `name: string` and `path: string`; a [[`ZemiMethod`](#zemimethod)]:[`ZemiRequestHandler`](#zemirequesthandler) needs to be provided if that path should have functionality, but doesn't need to be if the path is just present as a path-prefix for nested routes.\n\n```\n{\n   [ZemiMethod]: ZemiRequestHandler;\n   name: string;\n   path: string;\n   middleware?: Array\u003cRequestHandler\u003e;\n   routes?: Array\u003cZemiRoute\u003e;\n}\n```\n\n\u003cbr\u003e\n\n## Examples\n\nExamples are available in the [examples](https://github.com/yoaquim/zemi/blob/main/examples) dir:\n\n1. [Simple](https://github.com/yoaquim/zemi/blob/main/examples/simple.ts)\n\n2. [With Middleware](https://github.com/yoaquim/zemi/blob/main/examples/with-middleware.ts)\n\n3. [Using Named Routes For Redirects](https://github.com/yoaquim/zemi/blob/main/examples/using-named-routes-for-redirect.ts)\n \n4. [Using Reverse Routing](https://github.com/yoaquim/zemi/blob/main/examples/using-reverse-routing.ts)\n\n5. [With Param Inheritance from Parent Routes](https://github.com/yoaquim/zemi/blob/main/examples/nested-route-param-inheritance.ts)\n\n\u003cbr\u003e\n\n## Limitations\n\nzemi is a recursive library: it uses recursion across a number of operations in order to facilitate a low footprint and straightforward, declarative definitions.\n\nRecursive operations can break the call-stack by going over its limit, generating `Maximum call stack size exceeded` errors. This means that the recursive function was called too many times, and exceeded the limit placed on it by Node.\n\nWhile recursive functions _can_ be optimized via [tail call optimization](https://stackoverflow.com/questions/310974/what-is-tail-call-optimization) (TCO), that feature _has_ to be present in the environment being run for optimization to work.\n\nUnfortunately — as of Node 8.x — TCO is [no](https://stackoverflow.com/questions/23260390/node-js-tail-call-optimization-possible-or-not) [longer](https://stackoverflow.com/questions/42788139/es6-tail-recursion-optimisation-stack-overflow/42788286#42788286) [supported](https://bugs.chromium.org/p/v8/issues/detail?id=4698).\n\nThis means that, depending on what you're building and the size of your API, zemi might not be the right fit for you. zemi uses recursion when dealing with nested routes, so if your application has a very high number of nested-routes within nested-routes, chances are you might exceed the call stack.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoaquim%2Fzemi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoaquim%2Fzemi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoaquim%2Fzemi/lists"}