@prexjs/on-headers 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Prexjs (https://prexjs.com)
+Copyright (c) 2026 Sorabh (https://sorabh.org)
+
+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

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @prexjs/on-headers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Execute a listener when HTTP headers are about to be written to a response.**
+
+[![npm version](https://img.shields.io/npm/v/@prexjs/on-headers)](https://www.npmjs.com/package/@prexjs/on-headers)
+[![npm downloads](https://img.shields.io/npm/dm/@prexjs/on-headers)](https://www.npmjs.com/package/@prexjs/on-headers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-supported-blue)](https://www.typescriptlang.org/)
+
+`@prexjs/on-headers` intercepts `res.writeHead` and response flushes, executing a callback right before HTTP response headers are written to the client. This allows middleware (e.g. session managers, cookie setters, compression tools) to adjust headers at the last possible moment.
+
+## Features
+
+- Guarantees execution right before headers are sent to the client.
+- Automatically handles status code changes performed within listener callbacks.
+- Supports object and array arguments passed to `res.writeHead`.
+- Executes listeners in reverse order of addition (LIFO), allowing stacked middleware hooks.
+- Dual ES Module (`.mjs`) and CommonJS (`.cjs`) support with TypeScript definitions.
+- Zero external runtime dependencies.
+
+## Installation
+
+Install using your preferred package manager:
+
+```bash
+# npm
+npm install @prexjs/on-headers
+
+# pnpm
+pnpm add @prexjs/on-headers
+
+# Yarn
+yarn add @prexjs/on-headers
+
+# Bun
+bun add @prexjs/on-headers
+```
+
+## Quick start
+
+```ts
+import http from 'node:http';
+import onHeaders from '@prexjs/on-headers';
+
+const server = http.createServer((req, res) => {
+  const start = Date.now();
+
+  onHeaders(res, function () {
+    const duration = Date.now() - start;
+    this.setHeader('X-Response-Time', `${duration}ms`);
+  });
+
+  res.end('Hello World');
+});
+```
+
+Both default and named exports are supported:
+
+```ts
+import onHeaders, { onHeaders as namedOnHeaders } from '@prexjs/on-headers';
+```
+
+## Examples
+
+### Conditional status code updates
+
+```ts
+import http from 'node:http';
+import onHeaders from '@prexjs/on-headers';
+
+const server = http.createServer((req, res) => {
+  onHeaders(res, function () {
+    if (this.statusCode === 200 && req.headers['x-custom-flag']) {
+      this.statusCode = 201;
+    }
+  });
+
+  res.statusCode = 200;
+  res.end('Created');
+});
+```
+
+## Compatibility
+
+`@prexjs/on-headers` is designed for Node.js, Deno, and Bun HTTP servers utilizing `http.ServerResponse`.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.
+
+## Related projects
+
+- [prex.js](https://github.com/prexjs/prex.js) — prex.js monorepo and ecosystem.

package/lib/index.cjs

@@ -0,0 +1,7 @@
+/*!
+ * @prexjs/on-headers
+ * Copyright (c) 2026 Prexjs (https://prexjs.com)
+ * Copyright (c) 2026 Sorabh (https://Sorabh.org)
+ * MIT Licensed
+ */
+"use strict";function e(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}Object.defineProperty(exports,"__esModule",{value:!0});function t(e,t){let r=!1;return function(...o){const s=n.apply(this,o);return r||(r=!0,t.call(this),"number"==typeof s[0]&&this.statusCode!==s[0]&&(s[0]=this.statusCode,s.length=1)),e.apply(this,s)}}function r(e,r){if(!e)throw new TypeError("argument res is required");if("function"!=typeof r)throw new TypeError("argument listener must be a function");e.writeHead=t(e.writeHead,r)}function n(e,...t){const r=t.length+1,n=r>1&&"string"==typeof t[0]?2:1,s=r>=n+1?t[n-1]:void 0;this.statusCode=e,Array.isArray(s)?function(e,t){if(t.length&&Array.isArray(t[0]))!function(e,t){for(let r=0;r<t.length;r++){const n=t[r][0];n&&e.setHeader(n,t[r][1])}}(e,t);else{if(t.length%2!=0)throw new TypeError("headers array is malformed");o(e,t)}}(this,s):s&&function(e,t){const r=Object.keys(t);for(let n=0;n<r.length;n++){const o=r[n];o&&e.setHeader(o,t[o])}}(this,s);return[e,...t].slice(0,Math.min(r,n))}const o="function"==typeof e(require("node:http")).default.ServerResponse.prototype.appendHeader?function(e,t){for(let r=0;r<t.length;r+=2)e.removeHeader(t[r]);for(let r=0;r<t.length;r+=2){const n=t[r];n&&e.appendHeader(n,t[r+1])}}:function(e,t){for(let r=0;r<t.length;r+=2){const n=t[r];n&&e.setHeader(n,t[r+1])}};exports.default=r,exports.onHeaders=r;

package/lib/index.d.cts

@@ -0,0 +1,9 @@
+import http from 'node:http';
+
+type Listener = (this: http.ServerResponse) => void;
+/**
+ * Execute a listener when a response is about to write headers.
+ */
+declare function onHeaders(res: http.ServerResponse, listener: Listener): void;
+
+export { onHeaders as default, onHeaders };

package/lib/index.d.mts

@@ -0,0 +1,9 @@
+import http from 'node:http';
+
+type Listener = (this: http.ServerResponse) => void;
+/**
+ * Execute a listener when a response is about to write headers.
+ */
+declare function onHeaders(res: http.ServerResponse, listener: Listener): void;
+
+export { onHeaders as default, onHeaders };

package/lib/index.mjs

@@ -0,0 +1,7 @@
+/*!
+ * @prexjs/on-headers
+ * Copyright (c) 2026 Prexjs (https://prexjs.com)
+ * Copyright (c) 2026 Sorabh (https://Sorabh.org)
+ * MIT Licensed
+ */
+import e from"node:http";function t(e,t){let r=!1;return function(...o){const s=n.apply(this,o);return r||(r=!0,t.call(this),"number"==typeof s[0]&&this.statusCode!==s[0]&&(s[0]=this.statusCode,s.length=1)),e.apply(this,s)}}function r(e,r){if(!e)throw new TypeError("argument res is required");if("function"!=typeof r)throw new TypeError("argument listener must be a function");e.writeHead=t(e.writeHead,r)}function n(e,...t){const r=t.length+1,n=r>1&&"string"==typeof t[0]?2:1,s=r>=n+1?t[n-1]:void 0;this.statusCode=e,Array.isArray(s)?function(e,t){if(t.length&&Array.isArray(t[0]))!function(e,t){for(let r=0;r<t.length;r++){const n=t[r][0];n&&e.setHeader(n,t[r][1])}}(e,t);else{if(t.length%2!=0)throw new TypeError("headers array is malformed");o(e,t)}}(this,s):s&&function(e,t){const r=Object.keys(t);for(let n=0;n<r.length;n++){const o=r[n];o&&e.setHeader(o,t[o])}}(this,s);return[e,...t].slice(0,Math.min(r,n))}const o="function"==typeof e.ServerResponse.prototype.appendHeader?function(e,t){for(let r=0;r<t.length;r+=2)e.removeHeader(t[r]);for(let r=0;r<t.length;r+=2){const n=t[r];n&&e.appendHeader(n,t[r+1])}}:function(e,t){for(let r=0;r<t.length;r+=2){const n=t[r];n&&e.setHeader(n,t[r+1])}};export{r as default,r as onHeaders};

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@prexjs/on-headers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Execute a listener when HTTP headers are about to be written to a response.",
+  "authors": [
+    {
+      "name": "Prexjs",
+      "email": "hello@prexjs.com",
+      "url": "https://prexjs.com"
+    },
+    {
+      "name": "Sorabh",
+      "email": "hello@sorabh.org",
+      "url": "https://sorabh.org"
+    }
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "types": "./lib/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prexjs/prex.js.git",
+    "directory": "packages/on-headers"
+  },
+  "homepage": "https://github.com/prexjs/prex.js/tree/main/packages/on-headers#readme",
+  "bugs": {
+    "url": "https://github.com/prexjs/prex.js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "prexjs",
+    "on-headers",
+    "http",
+    "headers",
+    "writehead",
+    "response",
+    "middleware",
+    "listener",
+    "typescript"
+  ]
+}