@ublitzjs/core 0.0.1

package/README.md

@@ -0,0 +1,38 @@
+![μBlitz.js](./logo.png)
+<br/>
+
+# μBlitz.js - utility-library for uWebSockets.js
+
+On NPM you can find such packages:
+
+- @ublitzjs/core (THIS repo)
+- @ublitzjs/logger (colorful console)
+- @ublitzjs/static (send files)
+- @ublitzjs/payload (handling POST-like requests)
+- @ublitzjs/router (OpenAPI-like router for simple orientation)
+- @ublitzjs/openapi
+- @ublitzjs/dev-comments (Tool for removing CODE BETWEEN /\*\_START_DEV\_\*/ and /\*\_END_DEV\_\*/ comments)
+
+# Installation
+
+```ps1
+npm install "@ublitzjs/core"
+```
+
+Or with bun. Or whatever.
+
+# Preferences
+
+Supports CJS and ESM in ALL packages
+
+# <a href="./USAGE.md" target="_blank">Go to usage.md</a>
+
+# Comparison with others
+
+It is acclaimed, that Express.js, Fastify, and other frameworks are built to be very extensible and developer-friendly. It is enough to download needed packages, put them as middlewares, which handle everything behind the scenes, and do your own job. <br>
+
+But the "speed" of creating your app comes from so-called "abstractions". Their versatility is often considered an "overkill" and they usually overwhelm the RAM and slow down your app. Most people, however, still prefer "rapid typing" over speed of execution, under which I mean uWebSocket.js (which actually handles websockets AND http requests)<br>
+
+Though it IS performant, it handles only core features. Now there are solutions like "hyper-express", "ultimate-express", "uwebsockets-express", but they are just abstractions, created to be somehow faster then express, but hide the most important (and difficult) aspects of uWS.<br>
+
+This library is different. It doesn't take care of everything, but rather helps you do it yourself, using utilities.

package/USAGE.md

@@ -0,0 +1,319 @@
+> some examples will be shown using typescript, all examples are esm (but can also be cjs)
+
+# Setup main file
+
+In this section each code sample will show more features, so be ready to see them one by one.
+
+## no routers or other imports
+
+### without package
+
+```typescript
+import uWS from "uWebSockets.js";
+
+const server = uWS.App();
+
+server.any("/*", (res, req) => {
+  // manually handle this
+  res.writeStatus("404").end("Nothing to see here!");
+});
+
+// though I don't use "run", it is needed for example
+function run() {
+  server.listen(9001, (token) =>
+    token ? console.info("Start success") : console.error("Start failure")
+  );
+}
+
+run();
+```
+
+### with core package (low deps)
+
+```typescript
+import uWS from "uWebSockets.js";
+
+// c404 is an ArrayBuffer (not all codes are converted, don't worry), toAB - conversion helper
+import { c404, toAB } from "@ublitzjs/core";
+
+const server = uWS.App();
+
+var noFoundMessage = toAB("Nothing to see here!");
+server.any("/*", (res, req) => {
+  res.writeStatus(c404).end(notFoundMessage);
+});
+
+function run() {
+  server.listen(9001, (token) =>
+    token ? console.info("Start success") : console.error("Start failure")
+  );
+}
+
+run();
+```
+
+### with core package (better version)
+
+```typescript
+import uWS from "uWebSockets.js";
+
+// extendApp - lets you use or write extensions, notFoundConstructor - send 404 with a message
+import { extendApp, notFoundConstructor } from "@ublitzjs/core";
+
+// all extensions will be typed in typescript, so server.run call is also typed.
+const server = extendApp(
+  uWS.App(),
+  /* your extensions as a rest parameter. They will be bound to "server" */ {
+    run(/*for typescript*/ this: Server) {
+      this.listen(9001, (token) =>
+        token ? console.info("Start success") : console.error("Start failure")
+      );
+    },
+  } /*, you can put here as many as you want. */
+);
+
+server.any("/*", notFoundConstructor("Nothing to see here!"));
+
+// use your extension
+server.run();
+```
+
+And last example, just to show real-world use-case for extendApp
+
+```typescript
+import uWS from "uWebSockets.js";
+import { extendApp, notFoundConstructor } from "@ublitzjs/core";
+
+import { serverExtension as openapiExt } from "@ublitzjs/openapi";
+
+const server = extendApp(
+  uWS.App(),
+  // this is very basic, so for better examples - go find source repo
+  openapiExt({
+    openapi: "3.0.0",
+    info: {
+      title: "Some ublitzjs server",
+      version: "0.0.1",
+    },
+  }),
+  // your extension can also be here
+  {
+    run(this: Server) {
+      this.listen(9001, (token) =>
+        token ? console.info("Start success") : console.error("Start failure")
+      );
+    },
+  }
+);
+// this function is given by the extension
+await server.serveOpenApi("/docs", { build: false, path: "openapi.json" });
+
+server.any("/*", notFoundConstructor("Nothing to see here!"));
+
+server.run();
+```
+
+So in extendApp you put "extensions", as I call them.
+
+## With routers (mainly not @ublitzjs/router) and other imports
+
+### two modules with core package
+
+_main.js_
+
+```typescript
+import uWS from "uWebSockets.js";
+import { extendApp } from "@ublitzjs/core";
+import router from "./router.js";
+const server = extendApp(uWS.App());
+// register "plugins", not "extensions"
+server.register(router);
+server.listen(9001, () => {});
+```
+
+here you have imported your router and registered it as a plugin. So "extension" gives you NEW functionality, while "plugin" should use your current functionality
+
+_router.js_
+
+```typescript
+import type { Server } from "@ublitzjs/core";
+// for readability and
+export default (server: Server) => {
+  server.get("/simple", (res) => {
+    res.end("hello");
+  });
+};
+```
+
+### example with @ublitzjs/router
+
+_main.js_ - the same. Nothing changed at all <br>
+_router.js_
+
+```typescript
+import type { Server } from "@ublitzjs/core";
+import { Router } from "@ublitzjs/router";
+// again - better explanations in source repo.
+// Generally, router looks like OpenAPI
+const router = new Router({
+  // route
+  "/simple": {
+    // method
+    get(res) {
+      res.end("hello");
+    },
+  },
+});
+export default (server: Server) => {
+  router.bind(server).define("/simple", "get");
+};
+```
+
+So here I showed you how to setup a main file and split your code into modules
+
+# Headers
+
+## HeadersMap
+
+This class is used to convert all headers to ArrayBuffers and quickly set them on each request.
+
+```typescript
+import { HeadersMap, definePlugin, toAB, type Server } from "@ublitzjs/core";
+// init headers
+const htmlHeaders = new HeadersMap({
+  "Content-Type": "text/html",
+});
+// convert strings to ArrayBuffers -> it returns a function
+const setHeaders = htmlHeaders.prepare();
+
+export default (server: Server) => {
+  const html = toAB("<h1>Hello</h1>");
+  server.get("/", (res) => {
+    // and this function returns "res" object
+    setHeaders(res).end(html);
+  });
+};
+```
+
+Also there is HeadersMap.default (see it in the code itself), HeadersMap.baseObj (also in the code), and HeadersMap.remove (you remove unwanted headers)
+
+## setCSP
+
+Creates a string of CSP, using array parameters.
+
+```typescript
+// in response (not recommended)
+res.writeHeader(
+  "Content-Security-Policy",
+  setCSP({ "default-src": ["'self'"] })
+);
+// in HeadersMap
+import { setCSP, HeadersMap, /*basic settings*/ CSPDirs } from "@ublitzjs";
+new HeadersMap({
+  "Content-Security-Policy": setCSP(
+    {
+      ...CSPDirs,
+      "connect-src": ["'self'", "https://example.com"],
+    },
+    /*remove directives in a rest param*/
+    "img-src",
+    "object-src"
+  ),
+}).prepare();
+```
+
+## lowHeaders
+
+Greatly fits when you need to use request.getHeader("sec-websocket-extensions"), but miss a letter or two. <br>
+See example below in "uWS types / DocumentedWS and DocumentedWSBehavior"
+
+# registerAbort
+
+this utility lets you extend your handlers in a very asynchronous manner and nothing will ever brake.<br>
+Emitter used here is "tseep", which is faster than node:events.
+
+```typescript
+import type { HttpResponse } from "@ublitzjs/core";
+function myOnAbort(res: HttpResponse) {
+  res.emitter.once("abort", () => {
+    /*do something*/
+  });
+}
+server.get("/", (res) => {
+  // use it
+  registerAbort(res);
+  console.log(/*added on the response*/ res.aborted, res.emitter);
+
+  res.emitter.once("abort", () => {
+    console.log("ABORTED");
+    // as an example
+    stopDatabaseTransaction();
+  });
+
+  myOnAbort();
+  /*here you something*/
+});
+```
+
+It is heavily used in @ublitzjs/req-body and @ublitzjs/static to stop file streams
+If you want a more interesting use-case, <a href="./examples/AsyncFunction.mts">Go here</a>
+
+# uWS types
+
+Another benefit of using this package are additional typescript docs for uWS, that they haven't added yet (I mean index.d.ts has no description yet).
+
+## DeclarativeResponse
+
+This class helps you define faster and more optimized controllers, because they are prebuilt before execution.<br>
+
+Instead of sending response dynamically each time with <code>res.end()</code> you generate the whole response with all headers and body right on the start of the application.<br>
+
+It is not something, that ublitzjs created (only <code>.writeHeaders</code> method), but rather just description it gives you with the class
+
+```typescript
+import { DeclarativeResponse } from "@ublitzjs";
+server.get(
+  "/fast-response",
+  new Declarative()
+    .writeHeader("Content-Type", "text/plain")
+    /*spec method*/ .writeHeaders({ Allow: "GET" })
+    .end("HI")
+);
+```
+
+## DocumentedWS and DocumentedWSBehavior
+
+These types add 3 methods to websocket object: sendFirstFragment, sendFragment, sendLastFragment.<br>
+More detailed description <a href="./types/uws-types.d.ts">here</a>
+
+```typescript
+import type { DocumentedWSBehavior, lowHeaders } from "@ublitzjs/core";
+import uWS from "uWebSockets.js";
+const server = uWS.App();
+server.ws("/*", {
+  upgrade(res, req, context) {
+    res.upgrade(
+      { url: req.getUrl() },
+      req.getHeader</*adds typescript support*/ lowHeaders>(
+        "sec-websocket-key"
+      ),
+      req.getHeader<lowHeaders>("sec-websocket-protocol"),
+      req.getHeader<lowHeaders>("sec-websocket-extensions"),
+      context
+    );
+  },
+  async open(ws) {
+    ws.sendFirstFragment("hello1\n");
+    ws.sendFragment("hello2\n");
+    ws.sendLastFragment("end hello");
+  },
+} as DocumentedWSBehavior<{}> as any);
+```
+
+# Bundling
+
+Best efficiency and start time can be achieved if the code is bundled and minified.<br>
+For this purpose you can use "esbuild" (at least it was tested and worked for both cjs and esm formats).<br>
+The only thing to remember: when you use it for bundling, don't forget to put "uWebSockets.js" to "external" array.<br>
+<a href="./examples/esbuild.mjs">Example 1</a><br>
+<a href="./tests/esbuild/build.mjs">Dynamic example 2</a>

package/cjs/http-codes.cjs

@@ -0,0 +1,56 @@
+"use strict";
+var { toAB } = require("./index.cjs");
+var c411 = toAB("411");
+var c400 = toAB("400");
+var c413 = toAB("413");
+var c405 = toAB("405");
+var c404 = toAB("404");
+var c405Message = toAB("Method is not allowed");
+var allowHeader = toAB("Allow");
+function checkContentLength(res, req) {
+  var CL = Number(req.getHeader("content-length"));
+  if (!CL) {
+    res.finished = true;
+    res.cork(() => res.writeStatus(c411).endWithoutBody(0, true));
+    throw new Error("Wrong content-length", { cause: { CL } });
+  }
+  return CL;
+}
+function badRequest(res, error, causeForYou) {
+  res.finished = true;
+  if (!res.aborted) res.cork(() => res.writeStatus(c400).end(toAB(error)));
+  throw new Error("Bad request", { cause: causeForYou });
+}
+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.finished = true;
+  throw new Error("body too large", { cause: { limit } });
+}
+function seeOtherMethods(methodsArr) {
+  var methods = toAB(
+    methodsArr
+      .map((method) => method.toUpperCase())
+      .join(", ")
+      .replace("DEL", "DELETE")
+      .replace(/ WS,*/g, "")
+  );
+  return (res) =>
+    res.writeStatus(c405).writeHeader(allowHeader, methods).end(c405Message);
+}
+function notFoundConstructor(message = "Not found") {
+  var mes = toAB(message);
+  return (res) => res.writeStatus(c404).end(mes, true);
+}
+module.exports = {
+  badRequest,
+  checkContentLength,
+  notFoundConstructor,
+  seeOtherMethods,
+  tooLargeBody,
+  c400,
+  c404,
+  c405,
+  c411,
+  c413,
+};

package/cjs/http-headers.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var { toAB } = require("./index.cjs");
+var helmetHeaders = {
+  "X-Content-Type-Options": "nosniff",
+  "X-DNS-Prefetch-Control": "off",
+  "X-Frame-Options": "DENY",
+  "Referrer-Policy": "same-origin",
+  "X-Permitted-Cross-Domain-Policies": "none",
+  "X-Download-Options": "noopen",
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "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`,
+};
+class HeadersMap extends Map {
+  constructor(opts) {
+    super();
+    this.currentHeaders = opts;
+  }
+  remove(...keys) {
+    keys.forEach((key) => delete this.currentHeaders[key]);
+    return this;
+  }
+  prepare() {
+    for (const key in this.currentHeaders)
+      this.set(toAB(key), toAB(this.currentHeaders[key]));
+    return (this.currentHeaders = void 0), (res) => this.toRes(res);
+  }
+  toRes = (res) =>
+    res.cork(() => this.forEach((value, key) => res.writeHeader(key, value)));
+  static baseObj = helmetHeaders;
+  static default = new HeadersMap({ ...HeadersMap.baseObj }).prepare();
+}
+function setCSP(mainCSP, ...remove) {
+  var key;
+  var CSPstring = "";
+  remove.forEach((dir) => delete mainCSP[dir]);
+  for (key in mainCSP) CSPstring += `${key} ${mainCSP[key].join(" ")}; `;
+  return CSPstring;
+}
+var CSPDirs = {
+  "default-src": ["'self'"],
+  "base-uri": ["'self'"],
+  "font-src": ["'self'"],
+  "form-action": ["'self'"],
+  "frame-ancestors": ["'none'"],
+  "img-src": ["'self'"],
+  "connect-src": ["'self'"],
+  "object-src": ["'none'"],
+  "script-src": ["'self'"],
+  "script-src-attr": ["'none'"],
+  "script-src-elem": ["'self'"],
+  "style-src": ["'self'"],
+  "style-src-attr": ["'none'"],
+  "style-src-elem": ["'self'"],
+  "trusted-types": ["'none'"],
+  "upgrade-insecure-requests": [],
+  "worker-src": ["'self'"],
+  "media-src": ["'self'"],
+};
+module.exports = { CSPDirs, HeadersMap, setCSP };

package/cjs/index.cjs

@@ -0,0 +1,61 @@
+"use strict";
+var uWS = require("uWebSockets.js");
+var { Buffer } = require("node:buffer");
+
+var { EventEmitter } = require("tseep");
+function registerAbort(res) {
+  if (typeof res.aborted === "boolean")
+    throw new Error("abort already registered");
+  res.aborted = false;
+  res.emitter = new EventEmitter();
+  return res.onAborted(() => {
+    res.aborted = true;
+    res.emitter.emit("abort");
+  });
+}
+var closure = (param) => param();
+function extendApp(app, ...rest) {
+  app.register = function (plugin) {
+    return plugin(this), this;
+  };
+  app.onError = function (fn) {
+    return (this._errHandler = fn), this;
+  };
+  app._startPromises = [];
+  app.ready = function () {
+    return Promise.all(this._startPromises).then(
+      () => (this._startPromises = [])
+    );
+  };
+  app.route = function (opts, plugins) {
+    if (plugins) for (const p of plugins) p(opts, this);
+    return this[opts.method](opts.path, opts.controller);
+  };
+  for (const extension of rest) Object.assign(app, extension);
+  return app;
+}
+function toAB(data) {
+  var NodeBuf = data instanceof Buffer ? data : Buffer.from(data);
+  return NodeBuf.buffer.slice(
+    NodeBuf.byteOffset,
+    NodeBuf.byteOffset + NodeBuf.byteLength
+  );
+}
+var DeclarativeResponse = uWS.DeclarativeResponse;
+DeclarativeResponse.prototype.writeHeaders = function (headers) {
+  for (const key in headers) this.writeHeader(key, headers[key]);
+  return this;
+};
+
+module.exports = {
+  DeclarativeResponse,
+  extendApp,
+  registerAbort,
+  toAB,
+  closure,
+};
+Object.assign(
+  module.exports,
+  require("./http-headers.cjs"),
+  require("./http-codes.cjs")
+);

package/mjs/http-codes.mjs

@@ -0,0 +1,52 @@
+"use strict";
+import { toAB } from "./index.mjs";
+export var c411 = toAB("411");
+export var c400 = toAB("400");
+export var c413 = toAB("413");
+export var c405 = toAB("405");
+export var c404 = toAB("404");
+var c405Message = toAB("Method is not allowed");
+var allowHeader = toAB("Allow");
+var checkHeader = toAB("content-length");
+var checkMessage = toAB("Content-Length required to be > 0");
+function checkContentLength(res, req) {
+  var CL = Number(req.getHeader(checkHeader));
+  if (!CL) {
+    res.finished = true;
+    res.cork(() => res.writeStatus(c411).end(checkMessage));
+    throw new Error("Wrong content-length", { cause: { CL } });
+  }
+  return CL;
+}
+function badRequest(res, error, causeForYou) {
+  res.finished = true;
+  if (!res.aborted) res.cork(() => res.writeStatus(c400).end(toAB(error)));
+  throw new Error("Bad request", { cause: causeForYou });
+}
+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.finished = true;
+}
+function seeOtherMethods(methodsArr) {
+  var methods = toAB(
+    methodsArr
+      .map((method) => method.toUpperCase())
+      .join(", ")
+      .replace("DEL", "DELETE")
+      .replace(/ WS,*/g, "")
+  );
+  return (res) =>
+    res.writeStatus(c405).writeHeader(allowHeader, methods).end(c405Message);
+}
+function notFoundConstructor(message = "Not found") {
+  var mes = toAB(message);
+  return (res) => res.writeStatus(c404).end(mes, true);
+}
+export {
+  badRequest,
+  checkContentLength,
+  notFoundConstructor,
+  seeOtherMethods,
+  tooLargeBody,
+};

package/mjs/http-headers.mjs

@@ -0,0 +1,61 @@
+"use strict";
+import { toAB } from "./index.mjs";
+var helmetHeaders = {
+  "X-Content-Type-Options": "nosniff",
+  "X-DNS-Prefetch-Control": "off",
+  "X-Frame-Options": "DENY",
+  "Referrer-Policy": "same-origin",
+  "X-Permitted-Cross-Domain-Policies": "none",
+  "X-Download-Options": "noopen",
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "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`,
+};
+class HeadersMap extends Map {
+  constructor(opts) {
+    super();
+    this.currentHeaders = opts;
+  }
+  remove(...keys) {
+    return keys.forEach((key) => delete this.currentHeaders[key]), this;
+  }
+  prepare() {
+    for (const key in this.currentHeaders)
+      this.set(toAB(key), toAB(this.currentHeaders[key]));
+    return (this.currentHeaders = void 0), (res) => this.toRes(res);
+  }
+  toRes = (res) =>
+    res.cork(() => this.forEach((value, key) => res.writeHeader(key, value)));
+  static baseObj = helmetHeaders;
+  static default = new HeadersMap({ ...HeadersMap.baseObj }).prepare();
+}
+function setCSP(mainCSP, ...remove) {
+  var key;
+  var CSPstring = "";
+  remove.forEach((dir) => delete mainCSP[dir]);
+  for (key in mainCSP) CSPstring += `${key} ${mainCSP[key].join(" ")}; `;
+  return CSPstring;
+}
+var CSPDirs = {
+  "default-src": ["'self'"],
+  "base-uri": ["'self'"],
+  "font-src": ["'self'"],
+  "form-action": ["'self'"],
+  "frame-ancestors": ["'none'"],
+  "img-src": ["'self'"],
+  "connect-src": ["'self'"],
+  "object-src": ["'none'"],
+  "script-src": ["'self'"],
+  "script-src-attr": ["'none'"],
+  "script-src-elem": ["'self'"],
+  "style-src": ["'self'"],
+  "style-src-attr": ["'none'"],
+  "style-src-elem": ["'self'"],
+  "trusted-types": ["'none'"],
+  "worker-src": ["'self'"],
+  "media-src": ["'self'"],
+};
+export { CSPDirs, HeadersMap, setCSP };