@ublitzjs/core 1.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2025-2026 Daniel Dyryl <diril656@gmail.com>
+
+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

@@ -10,12 +10,14 @@ On NPM you can find such packages: (with @ublitzjs/ organization)
 - static (send files)
 - payload (handling POST-like requests)
 - router (OpenAPI-like router for simple orientation)
-- openapi
+- openapi 
 - preprocess (Code preprocessing + templating framework)
 - asyncapi
 - testing (coming soon)
 - auth (coming soon)
 
+The ones having version < 1.0.0 are unstable.
+
 # Installation
 
 ```ps1

package/dist/cjs/http-codes.js

@@ -1,5 +1,8 @@
 "use strict";
 
+/**
+* Yes, I have just deprecated the whole category. It will be completely removed in 2.0.0. When is it coming? Who knows
+* */
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
@@ -10,19 +13,16 @@ exports.notFoundConstructor = notFoundConstructor;
 exports.seeOtherMethods = seeOtherMethods;
 exports.tooLargeBody = tooLargeBody;
 var _index = require("./index.js");
-var c405Message = (0, _index.toAB)("Method is not allowed");
-var allowHeader = (0, _index.toAB)("Allow");
-var checkHeader = (0, _index.toAB)("content-length");
-var checkMessage = (0, _index.toAB)("Content-Length is required to be > 0 and to be an integer");
 /**
- * If something wrong is to content-length, sends 411 code and throws error with a "cause" == { CL : string}, sets res.finished = true
+ * @deprecated
+ * uWS actually checks content-length by itself
  */
 function checkContentLength(res, req) {
-  var header = req.getHeader(checkHeader);
+  var header = req.getHeader("content-length");
   var CL;
   if (!header || !Number.isInteger(CL = Number(header))) {
     res.finished = true;
-    res.cork(() => res.writeStatus(c411).end(checkMessage));
+    res.cork(() => res.writeStatus("411").end("Content-Length is required to be > 0 and to be an integer"));
     throw new Error("Wrong content-length", {
       cause: {
         CL: header
@@ -32,26 +32,27 @@ function checkContentLength(res, req) {
   return CL;
 }
 /**
- * sends http 400 and throws an Error with "causeForYou", sets res.finished = true
+ * @deprecated
+ * This function throws, so it is slow.
  */
 function badRequest(res, error, causeForYou) {
   res.finished = true;
-  if (!res.aborted) res.cork(() => res.writeStatus(c400).end((0, _index.toAB)(error)));
+  if (!res.aborted) res.cork(() => res.writeStatus("400").end((0, _index.toAB)(error)));
   throw new Error("Bad request", {
     cause: causeForYou
   });
 }
 /**
- * sends http 413, but doesn't throw an Error, sets res.finished = true
+ * @deprecated
+ * These are 2 lines of code.
  */
 function tooLargeBody(res, limit) {
-  var message = (0, _index.toAB)("Body is too large. Limit in bytes - " + limit);
-  if (!res.aborted) res.cork(() => res.writeStatus(c413).end(message));
+  if (!res.aborted) res.cork(() => res.writeStatus("413").end("Body is too large. Limit in bytes - " + limit));
   res.finished = true;
 }
 /**
- * Constructs function, which sends http 405 and sets http Allow header with all methods you passed.
- * It ignores "ws" and replaces "del" on "DELETE"
+ * @deprecated
+ * use "typedAllowHeader" instead
  */
 function seeOtherMethods(methodsArr) {
   if (new Set(methodsArr).size != methodsArr.length) throw new Error("the methods repeat");
@@ -68,32 +69,38 @@ function seeOtherMethods(methodsArr) {
     }
   }
   var methods = (0, _index.toAB)(arr.join(", "));
-  return res => res.writeStatus(c405).writeHeader(allowHeader, methods).end(c405Message);
+  return res => res.writeStatus("405").writeHeader("Allow", methods).end("Method is not allowed");
 }
 /**
- * Constructs the function, which sets 404 http code and sends the message you have specified
+ * @deprecated
+ * This is 1-2 lines of code
  */
 function notFoundConstructor(message = "Not found") {
   var mes = (0, _index.toAB)(message);
-  return res => res.writeStatus(c404).end(mes, true);
+  return res => res.writeStatus("404").end(mes, true);
 }
 /**
+ * @deprecated
  * code: required content length
  */
 var c411 = exports.c411 = (0, _index.toAB)("411");
 /**
+ * @deprecated
  * code: bad request
  */
 var c400 = exports.c400 = (0, _index.toAB)("400");
 /**
+ * @deprecated
  * code: payload too large
  */
 var c413 = exports.c413 = (0, _index.toAB)("413");
 /**
+ * @deprecated
  * code: method not allowed
  */
 var c405 = exports.c405 = (0, _index.toAB)("405");
 /**
+ * @deprecated
  * code: not found
  */
 var c404 = exports.c404 = (0, _index.toAB)("404");

package/dist/cjs/http-headers.js

@@ -3,10 +3,13 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.HeadersMap = exports.CSPDirs = void 0;
+exports.helmentHeaders = exports.HeadersMap = exports.CSPDirs = void 0;
+exports.parseRange = parseRange;
 exports.setCSP = setCSP;
+exports.staticHeaders = staticHeaders;
+exports.typedAllowHeader = typedAllowHeader;
 var _index = require("./index.js");
-var helmetHeaders = {
+var helmentHeaders = exports.helmentHeaders = {
   "X-Content-Type-Options": "nosniff",
   "X-DNS-Prefetch-Control": "off",
   "X-Frame-Options": "DENY",
@@ -17,14 +20,41 @@ var helmetHeaders = {
   "Cross-Origin-Opener-Policy": "same-origin",
   "Cross-Origin-Embedder-Policy": "require-corp",
   "Origin-Agent-Cluster": "?1"
-  //"Content-Security-Policy-Report-Only":"",
-  //"Strict-Transport-Security":`max-age=${60 * 60 * 24 * 365}; includeSubDomains`,
 };
 /**
- * A map containing all headers as ArrayBuffers, so speed remains. There are several use cases of it:
- * 1) Don't define them in requests ( post(res){new HeadersMap({...headers}).prepare().toRes(res)} ). This is slow. Define maps BEFORE actual usage.
- * 2) You can pass them in LightMethod or HeavyMethod in shared property (but handle it manually)
- * 3) Don't define them before writing status on request. uWebSockets.js after first written header considers response as successful and puts "200" code automatically. Set headers AFTER validation in class controllers (handler function) and after writing status (or don't write it at all. It will be 200).
+* This function is created as a replacement for "HeadersMap" (which became deprecated in 1.1.0).
+* The most overhead when sending request doesn't come from utf16 -> utf8 conversion, but from many subsequent res.writeHeader, which is JS->C++ switch.
+* To reduce an amount of calling headers, you can use manual string concatenation and HTTP header separator - CRLF.
+* @notice this function doesn't create completely ready data to send. Look a the example below
+* @notice2 its return-type LIES. In fact it is just a concatenated string, but TS lies just for LSP help for the second param and, as a result, last header, value to which should be written in res.writeHeader
+* @example
+* //if all headers don't change
+* var headers = staticHeaders({
+*   "Content-Type": "text/plain"
+* }, "Etag") // However "Etag" doesn't have value yet
+* * var littleFasterHeaders = Buffer.from(headers)
+* server.get("/", (res)=>{
+*   // we put ETag's value to the right. This way we can combine static + dynamic headers in one single call
+*   res.writeHeader(littleFasterHeaders, 'W/"' + 123 + '"')
+*   res.end("ok")
+*
+*  // underneath this is the same (gain speed but lose TypeScript. Not bad if your head is a compiler)
+*  res.writeHeader("Content-Type: text/plain\r\nETag", 'W/"' + 123 + '"')
+*  // you can make right side look same as well
+*  res.writeHeader<string>("Content-Type", 'text/plain\r\nETag: W/"' + 123 + '"')
+* })
+*
+* */
+function staticHeaders(headers, likelyDynamicHeader) {
+  var result = "";
+  for (var key in headers) {
+    result += key + ": " + headers[key] + "\r\n";
+  }
+  return result += likelyDynamicHeader;
+}
+/**
+ * @deprecated because using ArrayBuffers vs strings in headers doesn't bring much benefit, as it turned out after some benchmarks (+ it uses Map class, so that's even slower). It is going to be removed in 2.0.0. When is it coming? Who knows.
+ * And YES, I removed description of it. Stick to "staticHeaders" or CRLF manipulations
  */
 class HeadersMap extends Map {
   currentHeaders;
@@ -69,7 +99,7 @@ class HeadersMap extends Map {
    * @example
    * new HeadersMap({...HeadersMap.baseObj, "ownHeader":"hello world"}).remove("X-Download-Options")
    */
-  static baseObj = helmetHeaders;
+  static baseObj = helmentHeaders;
   /**
    * this is same as "toRes", but it uses HeadersMap.baseObj
    */
@@ -94,8 +124,6 @@ function setCSP(mainCSP, ...remove) {
  * Usual CSP directories. If you want more dirs:
  * 1) I will put more in soon
  * 2) use string concatenation (use BASE)
- * @example
- * new HeadersMap({...HeadersMap.baseObj, "Content-Security-Policy":setCSP({...CSPDirs}) + " your-dir: 'self';"})
  */
 var CSPDirs = exports.CSPDirs = {
   "default-src": ["'self'"],
@@ -115,4 +143,64 @@ var CSPDirs = exports.CSPDirs = {
   "trusted-types": ["'none'"],
   "worker-src": ["'self'"],
   "media-src": ["'self'"]
-};
+};
+var badRange = {
+  ok: false,
+  code: "400"
+};
+/**
+* "Range" http header requires validation, so here you get it
+* @example
+* var data = Buffer.allocUnsafe(1024*1024)
+* server.get("/largeData", (res, req)=>{
+*   var range = req.getHeader("range")
+*   if(!range) return res.end(data)
+*   // so parseRange might modify "range" to suit requirements + check if header is right
+*   var parsedRange = parseRange(range, data.length - 1, 64*1024)
+*   // might be
+*   if(!parsedRange.ok) return res.writeStatus(parsedRange.code).end("bad")
+* })
+* */
+function parseRange(range, maxEnd, maxChunk) {
+  if (range.length == 7 || range.slice(0, 6) != "bytes=") return badRange;
+  var dash = range.indexOf("-", 6);
+  if (dash == -1) return badRange;
+  var start = dash == 6 ? undefined : Number(range.slice(6, dash));
+  if (Number.isNaN(start)) return badRange;
+  var end = range.length == dash + 1 ? undefined : Number(range.slice(dash + 1));
+  if (Number.isNaN(end)) return badRange;
+  if (end === undefined) {
+    end = maxChunk ? Math.min(start + maxChunk, maxEnd) : maxEnd;
+  } else if (start === undefined) {
+    start = maxEnd - end;
+    end = maxEnd;
+  }
+  if (start >= end || start >= maxEnd) return {
+    ok: false,
+    code: "416"
+  };
+  return {
+    ok: true,
+    start: start,
+    end
+  };
+}
+/**
+* This function takes methods that you registered on an endpoint and formats them to suit "Allow" header.
+* */
+function typedAllowHeader(methodsArr) {
+  if (new Set(methodsArr).size != methodsArr.length) throw new Error("the methods repeat");
+  var arr = [];
+  loop: for (var method of methodsArr) {
+    switch (method) {
+      case "ws":
+        continue loop;
+      case "del":
+        arr.push("DELETE");
+        break;
+      default:
+        arr.push(method.toUpperCase());
+    }
+  }
+  return arr.join(", ");
+}

package/dist/cjs/index.js

@@ -47,7 +47,12 @@ _uWebSockets.DeclarativeResponse.prototype.writeHeaders = function (headers) {
 };
 /**
  * function to effortlessly mark response as aborted AND to attach an event emitter, so that you can easily scale the handler. If you don't need event emitter and only some res.aborted - set it by yourself (no overkill for the handler)
+ * If some utility expect import("@ublitzjs/core").HttpResponse, it means that they response to first go through this registerAbort
  * @param res
+ * @example
+ * console.log(Boolean(res.emitter)) // false
+ * registerAbort(res)
+ * console.log(Boolean(res.emitter)) // true
  */
 function registerAbort(res) {
   if (typeof res.aborted === "boolean") throw new Error("abort already registered");
@@ -92,7 +97,7 @@ function extendApp(app, ...rest) {
   return app;
 }
 /**
- * conversion to ArrayBuffer ('cause transferring strings to uWS is really slow)
+ * @deprecated this conversion to arrayBuffer is not really necessary. You just have Buffer.from(""). Slicing that is rarely needed, and even if it is, that takes 4 lines of code
  */
 function toAB(data) {
   var NodeBuf = data instanceof _nodeBuffer.Buffer ? data : _nodeBuffer.Buffer.from(data);

package/dist/esm/http-codes.js

@@ -1,43 +1,44 @@
 "use strict";
+/**
+* Yes, I have just deprecated the whole category. It will be completely removed in 2.0.0. When is it coming? Who knows
+* */
 import { toAB } from "./index.js";
-var c405Message = toAB("Method is not allowed");
-var allowHeader = toAB("Allow");
-var checkHeader = toAB("content-length");
-var checkMessage = toAB("Content-Length is required to be > 0 and to be an integer");
 /**
- * If something wrong is to content-length, sends 411 code and throws error with a "cause" == { CL : string}, sets res.finished = true
+ * @deprecated
+ * uWS actually checks content-length by itself
  */
 export function checkContentLength(res, req) {
-    var header = req.getHeader(checkHeader);
+    var header = req.getHeader("content-length");
     var CL;
     if (!header || !Number.isInteger(CL = Number(header))) {
         res.finished = true;
-        res.cork(() => res.writeStatus(c411).end(checkMessage));
+        res.cork(() => res.writeStatus("411").end("Content-Length is required to be > 0 and to be an integer"));
         throw new Error("Wrong content-length", { cause: { CL: header } });
     }
     return CL;
 }
 /**
- * sends http 400 and throws an Error with "causeForYou", sets res.finished = true
+ * @deprecated
+ * This function throws, so it is slow.
  */
 export function badRequest(res, error, causeForYou) {
     res.finished = true;
     if (!res.aborted)
-        res.cork(() => res.writeStatus(c400).end(toAB(error)));
+        res.cork(() => res.writeStatus("400").end(toAB(error)));
     throw new Error("Bad request", { cause: causeForYou });
 }
 /**
- * sends http 413, but doesn't throw an Error, sets res.finished = true
+ * @deprecated
+ * These are 2 lines of code.
  */
 export function tooLargeBody(res, limit) {
-    var message = toAB("Body is too large. Limit in bytes - " + limit);
     if (!res.aborted)
-        res.cork(() => res.writeStatus(c413).end(message));
+        res.cork(() => res.writeStatus("413").end("Body is too large. Limit in bytes - " + limit));
     res.finished = true;
 }
 /**
- * Constructs function, which sends http 405 and sets http Allow header with all methods you passed.
- * It ignores "ws" and replaces "del" on "DELETE"
+ * @deprecated
+ * use "typedAllowHeader" instead
  */
 export function seeOtherMethods(methodsArr) {
     if (new Set(methodsArr).size != methodsArr.length)
@@ -53,32 +54,38 @@ export function seeOtherMethods(methodsArr) {
         }
     }
     var methods = toAB(arr.join(", "));
-    return (res) => res.writeStatus(c405).writeHeader(allowHeader, methods).end(c405Message);
+    return (res) => res.writeStatus("405").writeHeader("Allow", methods).end("Method is not allowed");
 }
 /**
- * Constructs the function, which sets 404 http code and sends the message you have specified
+ * @deprecated
+ * This is 1-2 lines of code
  */
 export function notFoundConstructor(message = "Not found") {
     var mes = toAB(message);
-    return (res) => res.writeStatus(c404).end(mes, true);
+    return (res) => res.writeStatus("404").end(mes, true);
 }
 /**
+ * @deprecated
  * code: required content length
  */
 export var c411 = toAB("411");
 /**
+ * @deprecated
  * code: bad request
  */
 export var c400 = toAB("400");
 /**
+ * @deprecated
  * code: payload too large
  */
 export var c413 = toAB("413");
 /**
+ * @deprecated
  * code: method not allowed
  */
 export var c405 = toAB("405");
 /**
+ * @deprecated
  * code: not found
  */
 export var c404 = toAB("404");

package/dist/esm/http-headers.js

@@ -1,6 +1,6 @@
 "use strict";
 import { toAB } from "./index.js";
-var helmetHeaders = {
+export var helmentHeaders = {
     "X-Content-Type-Options": "nosniff",
     "X-DNS-Prefetch-Control": "off",
     "X-Frame-Options": "DENY",
@@ -11,14 +11,41 @@ var helmetHeaders = {
     "Cross-Origin-Opener-Policy": "same-origin",
     "Cross-Origin-Embedder-Policy": "require-corp",
     "Origin-Agent-Cluster": "?1",
-    //"Content-Security-Policy-Report-Only":"",
-    //"Strict-Transport-Security":`max-age=${60 * 60 * 24 * 365}; includeSubDomains`,
 };
 /**
- * A map containing all headers as ArrayBuffers, so speed remains. There are several use cases of it:
- * 1) Don't define them in requests ( post(res){new HeadersMap({...headers}).prepare().toRes(res)} ). This is slow. Define maps BEFORE actual usage.
- * 2) You can pass them in LightMethod or HeavyMethod in shared property (but handle it manually)
- * 3) Don't define them before writing status on request. uWebSockets.js after first written header considers response as successful and puts "200" code automatically. Set headers AFTER validation in class controllers (handler function) and after writing status (or don't write it at all. It will be 200).
+* This function is created as a replacement for "HeadersMap" (which became deprecated in 1.1.0).
+* The most overhead when sending request doesn't come from utf16 -> utf8 conversion, but from many subsequent res.writeHeader, which is JS->C++ switch.
+* To reduce an amount of calling headers, you can use manual string concatenation and HTTP header separator - CRLF.
+* @notice this function doesn't create completely ready data to send. Look a the example below
+* @notice2 its return-type LIES. In fact it is just a concatenated string, but TS lies just for LSP help for the second param and, as a result, last header, value to which should be written in res.writeHeader
+* @example
+* //if all headers don't change
+* var headers = staticHeaders({
+*   "Content-Type": "text/plain"
+* }, "Etag") // However "Etag" doesn't have value yet
+* * var littleFasterHeaders = Buffer.from(headers)
+* server.get("/", (res)=>{
+*   // we put ETag's value to the right. This way we can combine static + dynamic headers in one single call
+*   res.writeHeader(littleFasterHeaders, 'W/"' + 123 + '"')
+*   res.end("ok")
+*
+*  // underneath this is the same (gain speed but lose TypeScript. Not bad if your head is a compiler)
+*  res.writeHeader("Content-Type: text/plain\r\nETag", 'W/"' + 123 + '"')
+*  // you can make right side look same as well
+*  res.writeHeader<string>("Content-Type", 'text/plain\r\nETag: W/"' + 123 + '"')
+* })
+*
+* */
+export function staticHeaders(headers, likelyDynamicHeader) {
+    var result = "";
+    for (var key in headers) {
+        result += key + ": " + headers[key] + "\r\n";
+    }
+    return (result += likelyDynamicHeader);
+}
+/**
+ * @deprecated because using ArrayBuffers vs strings in headers doesn't bring much benefit, as it turned out after some benchmarks (+ it uses Map class, so that's even slower). It is going to be removed in 2.0.0. When is it coming? Who knows.
+ * And YES, I removed description of it. Stick to "staticHeaders" or CRLF manipulations
  */
 export class HeadersMap extends Map {
     currentHeaders;
@@ -68,7 +95,7 @@ export class HeadersMap extends Map {
      * @example
      * new HeadersMap({...HeadersMap.baseObj, "ownHeader":"hello world"}).remove("X-Download-Options")
      */
-    static baseObj = helmetHeaders;
+    static baseObj = helmentHeaders;
     /**
      * this is same as "toRes", but it uses HeadersMap.baseObj
      */
@@ -95,8 +122,6 @@ export function setCSP(mainCSP, ...remove) {
  * Usual CSP directories. If you want more dirs:
  * 1) I will put more in soon
  * 2) use string concatenation (use BASE)
- * @example
- * new HeadersMap({...HeadersMap.baseObj, "Content-Security-Policy":setCSP({...CSPDirs}) + " your-dir: 'self';"})
  */
 export var CSPDirs = {
     "default-src": ["'self'"],
@@ -117,3 +142,58 @@ export var CSPDirs = {
     "worker-src": ["'self'"],
     "media-src": ["'self'"],
 };
+var badRange = { ok: false, code: "400" };
+/**
+* "Range" http header requires validation, so here you get it
+* @example
+* var data = Buffer.allocUnsafe(1024*1024)
+* server.get("/largeData", (res, req)=>{
+*   var range = req.getHeader("range")
+*   if(!range) return res.end(data)
+*   // so parseRange might modify "range" to suit requirements + check if header is right
+*   var parsedRange = parseRange(range, data.length - 1, 64*1024)
+*   // might be
+*   if(!parsedRange.ok) return res.writeStatus(parsedRange.code).end("bad")
+* })
+* */
+export function parseRange(range, maxEnd, maxChunk) {
+    if (range.length == 7 || range.slice(0, 6) != "bytes=")
+        return badRange;
+    var dash = range.indexOf("-", 6);
+    if (dash == -1)
+        return badRange;
+    var start = dash == 6 ? undefined : Number(range.slice(6, dash));
+    if (Number.isNaN(start))
+        return badRange;
+    var end = range.length == dash + 1 ? undefined : Number(range.slice(dash + 1));
+    if (Number.isNaN(end))
+        return badRange;
+    if (end === undefined) {
+        end = maxChunk ? Math.min(start + maxChunk, maxEnd) : maxEnd;
+    }
+    else if (start === undefined) {
+        start = maxEnd - end;
+        end = maxEnd;
+    }
+    if (start >= end || start >= maxEnd)
+        return { ok: false, code: "416" };
+    return { ok: true, start: start, end };
+}
+/**
+* This function takes methods that you registered on an endpoint and formats them to suit "Allow" header.
+* */
+export function typedAllowHeader(methodsArr) {
+    if (new Set(methodsArr).size != methodsArr.length)
+        throw new Error("the methods repeat");
+    var arr = [];
+    loop: for (var method of methodsArr) {
+        switch (method) {
+            case "ws": continue loop;
+            case "del":
+                arr.push("DELETE");
+                break;
+            default: arr.push(method.toUpperCase());
+        }
+    }
+    return arr.join(", ");
+}

package/dist/esm/index.js

@@ -9,7 +9,12 @@ uWS.DeclarativeResponse.prototype.writeHeaders = function (headers) {
 };
 /**
  * function to effortlessly mark response as aborted AND to attach an event emitter, so that you can easily scale the handler. If you don't need event emitter and only some res.aborted - set it by yourself (no overkill for the handler)
+ * If some utility expect import("@ublitzjs/core").HttpResponse, it means that they response to first go through this registerAbort
  * @param res
+ * @example
+ * console.log(Boolean(res.emitter)) // false
+ * registerAbort(res)
+ * console.log(Boolean(res.emitter)) // true
  */
 export function registerAbort(res) {
     if (typeof res.aborted === "boolean")
@@ -57,7 +62,7 @@ export function extendApp(app, ...rest) {
     return app;
 }
 /**
- * conversion to ArrayBuffer ('cause transferring strings to uWS is really slow)
+ * @deprecated this conversion to arrayBuffer is not really necessary. You just have Buffer.from(""). Slicing that is rarely needed, and even if it is, that takes 4 lines of code
  */
 export function toAB(data) {
     var NodeBuf = data instanceof Buffer ? data : Buffer.from(data);

package/dist/types/http-codes.d.ts

@@ -1,43 +1,52 @@
 import type { HttpResponse as uwsHttpResponse } from "uWebSockets.js";
 import type { HttpRequest, HttpMethods } from "./index.ts";
 /**
- * If something wrong is to content-length, sends 411 code and throws error with a "cause" == { CL : string}, sets res.finished = true
+ * @deprecated
+ * uWS actually checks content-length by itself
  */
 export declare function checkContentLength(res: uwsHttpResponse, req: HttpRequest): number;
 /**
- * sends http 400 and throws an Error with "causeForYou", sets res.finished = true
+ * @deprecated
+ * This function throws, so it is slow.
  */
 export declare function badRequest(res: uwsHttpResponse, error: string, causeForYou: string): void;
 /**
- * sends http 413, but doesn't throw an Error, sets res.finished = true
+ * @deprecated
+ * These are 2 lines of code.
  */
 export declare function tooLargeBody(res: uwsHttpResponse, limit: number): void;
 /**
- * Constructs function, which sends http 405 and sets http Allow header with all methods you passed.
- * It ignores "ws" and replaces "del" on "DELETE"
+ * @deprecated
+ * use "typedAllowHeader" instead
  */
 export declare function seeOtherMethods(methodsArr: HttpMethods[]): (res: uwsHttpResponse, req: any) => any;
 /**
- * Constructs the function, which sets 404 http code and sends the message you have specified
+ * @deprecated
+ * This is 1-2 lines of code
  */
 export declare function notFoundConstructor(message?: string): (res: uwsHttpResponse, req: any) => any;
 /**
+ * @deprecated
  * code: required content length
  */
 export declare var c411: ArrayBuffer;
 /**
+ * @deprecated
  * code: bad request
  */
 export declare var c400: ArrayBuffer;
 /**
+ * @deprecated
  * code: payload too large
  */
 export declare var c413: ArrayBuffer;
 /**
+ * @deprecated
  * code: method not allowed
  */
 export declare var c405: ArrayBuffer;
 /**
+ * @deprecated
  * code: not found
  */
 export declare var c404: ArrayBuffer;

package/dist/types/http-headers.d.ts

@@ -1,5 +1,18 @@
+import { type HttpMethods } from "./index.js";
+export declare var helmentHeaders: {
+    readonly "X-Content-Type-Options": "nosniff";
+    readonly "X-DNS-Prefetch-Control": "off";
+    readonly "X-Frame-Options": "DENY";
+    readonly "Referrer-Policy": "same-origin";
+    readonly "X-Permitted-Cross-Domain-Policies": "none";
+    readonly "X-Download-Options": "noopen";
+    readonly "Cross-Origin-Resource-Policy": "same-origin";
+    readonly "Cross-Origin-Opener-Policy": "same-origin";
+    readonly "Cross-Origin-Embedder-Policy": "require-corp";
+    readonly "Origin-Agent-Cluster": "?1";
+};
 import type { HttpResponse as uwsHttpResponse } from "uWebSockets.js";
-type helmetHeadersT = {
+export type helmetHeadersT = {
     /**
      *  By adding this header you can declare that your site should only load resources that have explicitly opted-in to being loaded across origin.
      * "require-corp" LETS YOU USE new SharedArrayBuffer()
@@ -49,7 +62,7 @@ type helmetHeadersT = {
      * */
     "X-XSS-Protection"?: string;
 };
-type CORSHeader = {
+export type CORSHeader = {
     /**
      * The HTTP Access-Control-Allow-Credentials response header tells browsers whether the server allows credentials to be included in cross-origin HTTP requests.
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Credentials
@@ -96,7 +109,7 @@ type CORSHeader = {
      */
     "Access-Control-Request-Method": string;
 };
-type experimentalHeaders = {
+export type experimentalHeaders = {
     /**
      * @experimental
      * The HTTP Attribution-Reporting-Eligible request header indicates that the corresponding response is eligible to register an attribution source or trigger.
@@ -350,7 +363,7 @@ type experimentalHeaders = {
      * */
     "Use-As-Dictionary": string;
 };
-type simpleHeaders = {
+export type simpleHeaders = {
     /**
      * indicates which content types, expressed as MIME types, the sender is able to understand
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept
@@ -521,7 +534,7 @@ type simpleHeaders = {
   It should only be included in 206 Partial Content or 416 Range Not Satisfiable responses.
   @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Range
      */
-    "Content-Range": string;
+    "Content-Range": `bytes ${number}-${number}/*` | `bytes ${number}-${number}/${number}` | `bytes */${number}`;
     /**
      * The HTTP Content-Security-Policy response header allows website administrators to control resources the user agent is allowed to load for a given page.
      *
@@ -544,7 +557,7 @@ type simpleHeaders = {
      * You know this one. It is "text/html" or "video/mp4" or whatever
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Type
      */
-    "Content-Type": string;
+    "Content-Type": `${string}/${string}` | `${string}/${string}; ${string}`;
     /**
      * The HTTP Cookie request header contains stored HTTP cookies associated with the server (i.e., previously sent by the server with the Set-Cookie header or set in JavaScript using Document.cookie)
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cookie
@@ -565,7 +578,7 @@ type simpleHeaders = {
      * @see
      * https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag
      * */
-    Etag: string;
+    Etag: `W/"${string}"` | `"${string}"`;
     /**
      *The HTTP Expect request header indicates that there are expectations that need to be met by the server in order to handle the complete request successfully.
   
@@ -609,7 +622,7 @@ type simpleHeaders = {
      * The HTTP If-Match request header makes a request conditional. A server will return resources for GET and HEAD methods, or upload resource for PUT and other non-safe methods, only if the resource matches one of the ETag values in the If-Match request header. If the conditional does not match, the 412 Precondition Failed response is returned instead.
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Match
      * */
-    "If-Match": string;
+    "If-Match": `W/"${string}"` | `"${string}"` | "*";
     /**
    * The HTTP If-Modified-Since request header makes a request conditional. The server sends back the requested resource, with a 200 status, only if it has been modified after the date in the If-Modified-Since header. If the resource has not been modified since, the response is a 304 without any body, and the Last-Modified response header of the previous request contains the date of the last modification.
   
@@ -739,7 +752,7 @@ type simpleHeaders = {
   If the server sends back ranges, it uses the 206 Partial Content status code for the response. If the ranges are invalid, the server returns the 416 Range Not Satisfiable error.
    * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Range
   * */
-    Range: string;
+    Range: `bytes=${number}-${number}` | `bytes=${number}-` | `bytes=-${number}`;
     /**
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referer
      * */
@@ -912,10 +925,33 @@ export type BaseHeaders = Partial<simpleHeaders & helmetHeadersT & experimentalH
     [key: string]: string;
 }>;
 /**
- * A map containing all headers as ArrayBuffers, so speed remains. There are several use cases of it:
- * 1) Don't define them in requests ( post(res){new HeadersMap({...headers}).prepare().toRes(res)} ). This is slow. Define maps BEFORE actual usage.
- * 2) You can pass them in LightMethod or HeavyMethod in shared property (but handle it manually)
- * 3) Don't define them before writing status on request. uWebSockets.js after first written header considers response as successful and puts "200" code automatically. Set headers AFTER validation in class controllers (handler function) and after writing status (or don't write it at all. It will be 200).
+* This function is created as a replacement for "HeadersMap" (which became deprecated in 1.1.0).
+* The most overhead when sending request doesn't come from utf16 -> utf8 conversion, but from many subsequent res.writeHeader, which is JS->C++ switch.
+* To reduce an amount of calling headers, you can use manual string concatenation and HTTP header separator - CRLF.
+* @notice this function doesn't create completely ready data to send. Look a the example below
+* @notice2 its return-type LIES. In fact it is just a concatenated string, but TS lies just for LSP help for the second param and, as a result, last header, value to which should be written in res.writeHeader
+* @example
+* //if all headers don't change
+* var headers = staticHeaders({
+*   "Content-Type": "text/plain"
+* }, "Etag") // However "Etag" doesn't have value yet
+* * var littleFasterHeaders = Buffer.from(headers)
+* server.get("/", (res)=>{
+*   // we put ETag's value to the right. This way we can combine static + dynamic headers in one single call
+*   res.writeHeader(littleFasterHeaders, 'W/"' + 123 + '"')
+*   res.end("ok")
+*
+*  // underneath this is the same (gain speed but lose TypeScript. Not bad if your head is a compiler)
+*  res.writeHeader("Content-Type: text/plain\r\nETag", 'W/"' + 123 + '"')
+*  // you can make right side look same as well
+*  res.writeHeader<string>("Content-Type", 'text/plain\r\nETag: W/"' + 123 + '"')
+* })
+*
+* */
+export declare function staticHeaders<T extends keyof RequiredBaseHeaders | (string & {})>(headers: BaseHeaders, likelyDynamicHeader: T): T;
+/**
+ * @deprecated because using ArrayBuffers vs strings in headers doesn't bring much benefit, as it turned out after some benchmarks (+ it uses Map class, so that's even slower). It is going to be removed in 2.0.0. When is it coming? Who knows.
+ * And YES, I removed description of it. Stick to "staticHeaders" or CRLF manipulations
  */
 export declare class HeadersMap<Opts extends BaseHeaders> extends Map {
     currentHeaders: undefined | Opts;
@@ -963,8 +999,6 @@ type CSP = Partial<typeof CSPDirs & {
  * Usual CSP directories. If you want more dirs:
  * 1) I will put more in soon
  * 2) use string concatenation (use BASE)
- * @example
- * new HeadersMap({...HeadersMap.baseObj, "Content-Security-Policy":setCSP({...CSPDirs}) + " your-dir: 'self';"})
  */
 export declare var CSPDirs: {
     /**
@@ -1036,5 +1070,31 @@ export declare var CSPDirs: {
      */
     "media-src": string[];
 };
-export type lowHeaders = Lowercase<keyof (simpleHeaders & helmetHeadersT & experimentalHeaders & CORSHeader)>;
+export type RequiredBaseHeaders = (simpleHeaders & helmetHeadersT & experimentalHeaders & CORSHeader);
+export type lowHeaders = Lowercase<keyof RequiredBaseHeaders>;
+/**
+* "Range" http header requires validation, so here you get it
+* @example
+* var data = Buffer.allocUnsafe(1024*1024)
+* server.get("/largeData", (res, req)=>{
+*   var range = req.getHeader("range")
+*   if(!range) return res.end(data)
+*   // so parseRange might modify "range" to suit requirements + check if header is right
+*   var parsedRange = parseRange(range, data.length - 1, 64*1024)
+*   // might be
+*   if(!parsedRange.ok) return res.writeStatus(parsedRange.code).end("bad")
+* })
+* */
+export declare function parseRange(range: string, maxEnd: number, maxChunk: number): {
+    ok: false;
+    code: "400" | "416";
+} | {
+    ok: true;
+    start: number;
+    end: number;
+};
+/**
+* This function takes methods that you registered on an endpoint and formats them to suit "Allow" header.
+* */
+export declare function typedAllowHeader(methodsArr: HttpMethods[]): string;
 export {};

package/dist/types/index.d.ts

@@ -1,10 +1,15 @@
-import type { BaseHeaders, lowHeaders } from "./http-headers.js";
+import type { BaseHeaders, lowHeaders, RequiredBaseHeaders } from "./http-headers.js";
 import { Buffer } from "node:buffer";
 import { EventEmitter } from "tseep";
 import type { CompressOptions, WebSocket, HttpRequest as uwsHttpRequest, TemplatedApp, HttpResponse as uwsHttpResponse, RecognizedString, us_socket_context_t } from "uWebSockets.js";
 /**
  * function to effortlessly mark response as aborted AND to attach an event emitter, so that you can easily scale the handler. If you don't need event emitter and only some res.aborted - set it by yourself (no overkill for the handler)
+ * If some utility expect import("@ublitzjs/core").HttpResponse, it means that they response to first go through this registerAbort
  * @param res
+ * @example
+ * console.log(Boolean(res.emitter)) // false
+ * registerAbort(res)
+ * console.log(Boolean(res.emitter)) // true
  */
 export declare function registerAbort(res: uwsHttpResponse): HttpResponse;
 /**
@@ -88,26 +93,47 @@ export interface HttpResponse<UserDataForWS = {}> extends uwsHttpResponse {
      */
     collect: (...any: any[]) => any;
     /**
-     * An event emitter, which lets you subscribe several listeners to "abort" event OR your own events, defined with Symbol().
+     * An event emitter, which lets you subscribe several listeners to "abort" event OR your own events, defined with Symbol() | other string
+     * @example
+     * res.emitter.once("abort", ()=>{
+     *   console.log("I have to clean up some random file descriptor")
+     *   // do cleanup
+     * })
      */
     emitter: EventEmitter<{
         abort: () => void;
         [k: symbol]: (...any: any[]) => void;
     }>;
     /**
-     * changes when res.onAborted fires.
+     * changes when res.onAborted fires (you have to use registerAbort for this)
      */
     aborted?: boolean;
     /**
      * You should set it manually when ending the response. Particularly useful if some error has fired and you are doubting whether res.aborted is a sufficient flag.
+     * @example
+     * function endResponse(res) {
+     *   if(res.aborted) return;
+     *   res.end("alright")
+     *   res.finished = true;
+     * }
      */
     finished?: boolean;
+    /**
+    * Writes key and value to HTTP response. See writeStatus and corking.
+    * It can actually write several values in a row, just be careful with string concatenation. If headers never change - use staticHeaders (and save typescript safety)
+    * @example
+    * res.writeHeader("Content-Type", "text/plain").writeHeader("Accept-Ranges", "bytes")
+    * // and a faster trick
+    * res.writeHeader("Content-Type: text/plain\r\nAccept-Ranges", "bytes")
+    * */
+    writeHeader<Key extends keyof RequiredBaseHeaders | Omit<RecognizedString, string> | (string & {})>(key: Key, val: Key extends keyof RequiredBaseHeaders ? RequiredBaseHeaders[Key] : RecognizedString): HttpResponse;
 }
 /**This HttpRequest is same as original uWS.HttpRequest, but getHeader method is typed for additional tips
  * @example
  * import {lowHeaders} from "@ublitzjs/core"
- * // some handler later
+ * // some handler later (not compulsory to specify lowHeaders. It is a default behaviour)
  * req.getHeader<lowHeaders>("content-type")
+ *
  */
 export interface HttpRequest extends uwsHttpRequest {
     getHeader<T extends RecognizedString = lowHeaders>(a: T): string;
@@ -128,7 +154,7 @@ type MergeObjects<T extends any[]> = T extends [infer First, ...infer Rest] ? Fi
  */
 export declare function extendApp<T extends object[]>(app: TemplatedApp, ...rest: T): Server & MergeObjects<T>;
 /**
- * conversion to ArrayBuffer ('cause transferring strings to uWS is really slow)
+ * @deprecated this conversion to arrayBuffer is not really necessary. You just have Buffer.from(""). Slicing that is rarely needed, and even if it is, that takes 4 lines of code
  */
 export declare function toAB(data: Buffer | string): ArrayBuffer;
 /**
@@ -220,6 +246,9 @@ export interface DocumentedWSBehavior<UserData> {
      */
     upgrade?: (res: HttpResponse<UserData>, req: HttpRequest, context: us_socket_context_t) => void | Promise<void>;
 }
+/**
+* let's believe, that in 20.61.0+ versions we get writeStatus.
+* */
 export type DeclarativeResType = {
     writeHeader(key: string, value: string): DeclarativeResType;
     writeQueryValue(key: string): DeclarativeResType;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@ublitzjs/core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "types": "./dist/types/index.d.ts",
-  "files": ["dist"],
+  "files": ["dist", "LICENSE"],
   "typesVersions": {
     "*": {
       ".": ["./dist/types/index.d.ts"]
     }
   },
+  "license": "MIT",
   "exports": {
     "types": "./dist/types/index.d.ts",
     "require": "./dist/cjs/index.js",
@@ -26,6 +27,7 @@
     "@babel/plugin-transform-modules-commonjs": "^7.28.6",
     "@types/node": "^25.2.1",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "4.0.18",
     "esbuild": "^0.25.12",
     "tsd": "^0.33.0",
     "vitest": "^4.0.8",
@@ -37,7 +39,7 @@
     "build:cjs": "babel dist/esm --out-dir dist/cjs",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "npm run build:types && npm run build:esm && npm run build:cjs",
-    "test": "tsd && vitest run"
+    "test": "tsd && vitest run tests/index.test.ts --coverage"
   },
   "tsd": {
     "directory": "tests"