@couimet/execution-context-http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Ouimet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @couimet/execution-context-http
+
+[![npm version](https://img.shields.io/npm/v/@couimet/execution-context-http.svg?style=flat-square)](https://www.npmjs.com/package/@couimet/execution-context-http) [![Coverage](https://codecov.io/gh/couimet/ts-npm-packages/branch/main/graph/badge.svg?flag=execution-context-http)](https://codecov.io/gh/couimet/ts-npm-packages?flag=execution-context-http) [![npm downloads](https://img.shields.io/npm/dm/@couimet/execution-context-http.svg?style=flat-square)](https://www.npmjs.com/package/@couimet/execution-context-http)
+
+`@couimet/execution-context-http` names the HTTP headers that carry a correlation id and a request id between services. The `HttpHeaders` enum holds the wire names, so inbound parsing and outbound writing share one spelling. The `firstHeaderValue` helper turns a raw inbound value into the single string that `ExecutionContext.run()` accepts. The package has no runtime dependencies and no framework dependency. It lets the core [`@couimet/execution-context`](https://github.com/couimet/ts-npm-packages/tree/main/packages/execution-context) package stay free of HTTP concerns.
+
+## Install
+
+```bash
+pnpm add @couimet/execution-context @couimet/execution-context-http
+```
+
+## Usage
+
+Read the header names off the enum instead of hard-coding strings:
+
+```typescript
+import { HttpHeaders } from '@couimet/execution-context-http';
+
+HttpHeaders.CorrelationId; // 'x-correlation-id'
+HttpHeaders.RequestId; // 'x-request-id'
+```
+
+An adapter uses the enum in both directions. It reads the names to pull the ids off an incoming request and reduce each value to one string. Then it echoes the same names back when it writes the response. One enum keeps the two directions in sync:
+
+```typescript
+import { ExecutionContext } from '@couimet/execution-context';
+import { firstHeaderValue, HttpHeaders } from '@couimet/execution-context-http';
+
+// Inbound: read the wire names off the request. A repeated header arrives as a
+// string[] under Node's IncomingHttpHeaders, so reduce each value to one string.
+const correlationId = firstHeaderValue(request.headers[HttpHeaders.CorrelationId]);
+const requestId = firstHeaderValue(request.headers[HttpHeaders.RequestId]);
+
+// Prime a scope for the request handler.
+ExecutionContext.run({ correlationId, requestId }, () => {
+  const result = handler();
+
+  // Outbound, while the scope is still active: echo the ids on the response.
+  // run() generates a fresh id when the request carries none.
+  response.setHeader(HttpHeaders.CorrelationId, ExecutionContext.correlationId.toString());
+  response.setHeader(HttpHeaders.RequestId, ExecutionContext.requestId.toString());
+
+  return result;
+});
+```
+
+## API reference
+
+The barrel re-exports two modules: `firstHeaderValue` and `HttpHeaders`.
+
+### firstHeaderValue
+
+Reduces a raw request-header value to the single string that `ExecutionContext.run()` accepts. Node's `IncomingHttpHeaders` can present a repeated header as a `string[]`, and `run()` accepts only `string | undefined`.
+
+```typescript
+function firstHeaderValue(value: string | string[] | undefined): string | undefined;
+```
+
+- Returns the value when it is a non-empty primitive string.
+- Returns the first value when a header repeats and the first value is a non-empty string.
+- Returns undefined when the header is absent or its value is empty, so `run()` generates a fresh id.
+
+### HttpHeaders
+
+The `HttpHeaders` enum:
+
+```typescript
+enum HttpHeaders {
+  CorrelationId = 'x-correlation-id',
+  RequestId = 'x-request-id',
+}
+```
+
+The member values are the lower-case wire header names used when writing a response. When an adapter reads the ids off a request, it cannot assume the headers object lower-cases its keys the way Node's `IncomingHttpHeaders` does. A runtime that preserves case can present `X-Correlation-Id` where the enum reads `x-correlation-id`, so the adapter should look the values up case-insensitively or normalize the header keys to lower case first. When a header repeats, Node's `IncomingHttpHeaders` presents the values as a `string[]`; reduce them to one string with `firstHeaderValue` before priming `run()`, which accepts only `string | undefined`. When an adapter writes a response, it echoes the id held in the active scope. Because `run()` generates a fresh id when the request carried none, the response carries both headers on every request. A downstream consumer cannot tell an id the caller provided from one this adapter generated.
+
+## Related packages
+
+- [`@couimet/execution-context`](https://github.com/couimet/ts-npm-packages/tree/main/packages/execution-context) is the runtime that consumes these names. Its `ExecutionContext.run()` primes the ids parsed from the headers.
+
+A framework adapter reads the names from this package, pulls the ids off the incoming request, and wraps `ExecutionContext.run()`. Each adapter lives in its own package named after its framework, such as `@couimet/execution-context-http-express`. The core package never depends on HTTP or a framework.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Reduces a raw request-header value to the single string that ExecutionContext.run() accepts.
+ * Node's IncomingHttpHeaders can present a repeated header as a string[]; the first value wins.
+ * A missing or empty value stays undefined, so run() generates a fresh id.
+ */
+declare function firstHeaderValue(value: string | string[] | undefined): string | undefined;
+
+declare enum HttpHeaders {
+    CorrelationId = "x-correlation-id",
+    RequestId = "x-request-id"
+}
+
+export { HttpHeaders, firstHeaderValue };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reduces a raw request-header value to the single string that ExecutionContext.run() accepts.
+ * Node's IncomingHttpHeaders can present a repeated header as a string[]; the first value wins.
+ * A missing or empty value stays undefined, so run() generates a fresh id.
+ */
+declare function firstHeaderValue(value: string | string[] | undefined): string | undefined;
+
+declare enum HttpHeaders {
+    CorrelationId = "x-correlation-id",
+    RequestId = "x-request-id"
+}
+
+export { HttpHeaders, firstHeaderValue };

package/dist/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HttpHeaders: () => HttpHeaders,
+  firstHeaderValue: () => firstHeaderValue
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/firstHeaderValue.ts
+function firstHeaderValue(value) {
+  const first = typeof value === "string" ? value : value?.[0];
+  return first === "" ? void 0 : first;
+}
+
+// src/httpHeaders.ts
+var HttpHeaders = /* @__PURE__ */ ((HttpHeaders2) => {
+  HttpHeaders2["CorrelationId"] = "x-correlation-id";
+  HttpHeaders2["RequestId"] = "x-request-id";
+  return HttpHeaders2;
+})(HttpHeaders || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HttpHeaders,
+  firstHeaderValue
+});

package/dist/index.mjs

@@ -0,0 +1,16 @@
+// src/firstHeaderValue.ts
+function firstHeaderValue(value) {
+  const first = typeof value === "string" ? value : value?.[0];
+  return first === "" ? void 0 : first;
+}
+
+// src/httpHeaders.ts
+var HttpHeaders = /* @__PURE__ */ ((HttpHeaders2) => {
+  HttpHeaders2["CorrelationId"] = "x-correlation-id";
+  HttpHeaders2["RequestId"] = "x-request-id";
+  return HttpHeaders2;
+})(HttpHeaders || {});
+export {
+  HttpHeaders,
+  firstHeaderValue
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@couimet/execution-context-http",
+  "version": "0.1.0",
+  "description": "Framework-free HTTP transport constants (x-correlation-id, x-request-id) for @couimet/execution-context",
+  "homepage": "https://github.com/couimet/ts-npm-packages/tree/main/packages/execution-context-http#readme",
+  "bugs": {
+    "url": "https://github.com/couimet/ts-npm-packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:couimet/ts-npm-packages.git",
+    "directory": "packages/execution-context-http"
+  },
+  "license": "MIT",
+  "author": "Charles Ouimet <charles.ouimet@gmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "prettier": "@couimet/eslint-config/prettier",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^26.2.0",
+    "eslint": "^10.8.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.9.6",
+    "ts-jest": "^29.4.12",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "@couimet/eslint-config": "1.3.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist coverage *.tsbuildinfo",
+    "clean:all": "pnpm clean && rm -rf node_modules .eslintcache *.log",
+    "clean:deps": "rm -rf node_modules",
+    "format": "prettier --check .",
+    "test": "jest --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}