{"id":19622149,"url":"https://github.com/commercetools/express-request-correlator","last_synced_at":"2025-04-28T03:32:24.548Z","repository":{"id":36459528,"uuid":"208260948","full_name":"commercetools/express-request-correlator","owner":"commercetools","description":"An express middleware to help tracing correlation IDs","archived":false,"fork":false,"pushed_at":"2025-04-28T02:48:18.000Z","size":4444,"stargazers_count":4,"open_issues_count":13,"forks_count":0,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-28T03:30:05.075Z","etag":null,"topics":["audit-frontend","devops","express","middleware","monitoring"],"latest_commit_sha":null,"homepage":"","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/commercetools.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-09-13T12:32:36.000Z","updated_at":"2024-06-17T07:25:42.000Z","dependencies_parsed_at":"2023-10-27T17:24:37.562Z","dependency_job_id":"86622bdf-befc-4f63-8013-718751e68add","html_url":"https://github.com/commercetools/express-request-correlator","commit_stats":{"total_commits":50,"total_committers":8,"mean_commits":6.25,"dds":0.26,"last_synced_commit":"d8a5305c908dc5fda1bce9186eee117dc7f27669"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fexpress-request-correlator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fexpress-request-correlator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fexpress-request-correlator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fexpress-request-correlator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercetools","download_url":"https://codeload.github.com/commercetools/express-request-correlator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251246358,"owners_count":21558762,"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":["audit-frontend","devops","express","middleware","monitoring"],"created_at":"2024-11-11T11:26:13.058Z","updated_at":"2025-04-28T03:32:23.492Z","avatar_url":"https://github.com/commercetools.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Logo\" height=\"150\" src=\"https://raw.githubusercontent.com/commercetools/express-request-correlator/master/logo.png\" /\u003e\u003cbr /\u003e\u003cbr /\u003e\n\u003c/p\u003e\n\n\u003ch2 align=\"center\"\u003e🧷 Express middleware to help tracing correlation IDs ⚙️\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/commercetools/express-request-correlator/actions\"\u003e\n    \u003cimg alt=\"CI Status\" src=\"https://github.com/commercetools/express-request-correlator/workflows/express-request-correlator/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003cimg alt=\"Made with Coffee\" src=\"https://img.shields.io/badge/made%20with-%E2%98%95%EF%B8%8F%20coffee-yellow.svg\" /\u003e\n\u003c/p\u003e\n\n## ❯ Why another middleware for express to work with correlation ids?\n\n\u003e This packages is a combination of observations and experiences we have had with other middlewares upon whose ideas we build:\n\n1. 🎨 **Customized** correlation ids: sometimes correlation ids need customization. For instance adding prefix based on the incoming request's origin.\n2. 🍕 **Forwarding** correlation ids: oftentimes an incoming correlation id needs to be forwarded as a header to another request (e.g. a `fetch` call).\n3. 🏄🏻 **Opting out** of correlation ids: cases exist where a correlation id can or should not be generated while the fact should be logged\n4. 👌🏼 **Inspecting** correlation ids: the correlation id of a request should be easy to extract without knowing the specific header it is passed under\n\n## ❯ Installation\n\nDepending on the preferred package manager:\n\n`yarn add @commercetools/express-request-correlator`\n\nor\n\n`npm i @commercetools/express-request-correlator --save`\n\n## ❯ Concepts\n\nA correlation id, can be referred to as a unique identifier that is attached to requests that allow grouping them as a transaction or event chain. In the case of multiple microservices it is used to correlate an incoming request to other resulting requests to other services. As a result a correlation ids should be passed on when found on an incoming request. If not found they should be generated early to have a correlatable request/transaction chain as soon as possible. Ultimately, this helps enabling a concept called distributed tracing in a distributed systems by for instance graphing a sequence diagram of multiple requests across various services.\n\nUsually correlation ids are passed as a header. The specific name of that header differs. Often `X-Correlation-Id` is used. Generally multiple services should agree on a shared name and location (e.g. header) of the id. However, it is possible that service `A` makes a request with a correlation id named (`X-Request-Id`) to service `B` which forwards it as `X-Correlation-Id`.\n\n## ❯ Documentation\n\nThe `express-request-correlator` comes with a couple of options it can be configured with:\n\n- `headerName`: the name of the header on which a new correlation id will be set on. Defaults to `X-Correlation-Id`.\n- `generateId`: a function called whenever an incoming request does not have a correlation id. Receives the `request` within its options argument.\n\nAn example configuration would be:\n\n```js\nimport { createRequestCorrelatorMiddleware } from '@commercetools/express-request-correlator';\n\napp.use(createRequestCorrelatorMiddleware());\n```\n\n1. The middleware adds a correlation id to each response as a header for debugging\n   - The previously received id is forwarded/used or a new id is generated\n2. The middleware itself exposes a property called `correlator` (more below) onto each incoming request\n   - This object allows receiving the correlation id in other parts of the request chain\n\nConfiguring the middleware on your express application exposes a `correlator` property on each request. See type `TRequestCorrelator`.\n\n1. If for instance you need to retrieve the current request's correlation id invoke `request.correlator.getCorrelationId()`\n2. If you want to forward the correlation id to another request's headers run `request.correlator.forwardCorrelationId({ headers })`\n   - This will mutate the passed in headers to contain the previous request's correlation id\n\nNote, that `getCorrelationId` and `forwardCorrelationId` both accept a object with configuration:\n\n```js\n{\n  ifNotDefined: () =\u003e TCorrelationId;\n}\n```\n\nWhenever `ifNotDefined` is passed it can be used as a last resort to generate a new correlation id given the request does not already have one. Another use case is logging. Whenever `ifNotDefined` is not passed the \"globally\" configured `generate` function will be used if no correlation id is present on the request.\n\n## ❯ Testing\n\nIn case you want to create a test correlator you can use the `createRequestCorrelatorMock` function on the `testUtils` object. It will create a mocked correlator with the same API as the actual correlator.\n\n```js\nimport { createRequestCorrelatorMock } from '@commercetools/express-request-correlator/test-utils';\n\ncreateRequestCorrelatorMock();\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fexpress-request-correlator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercetools%2Fexpress-request-correlator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fexpress-request-correlator/lists"}