@ublitzjs/core 0.0.1

package/mjs/index.mjs

@@ -0,0 +1,51 @@
+"use strict";
+import uWS from "uWebSockets.js";
+import { Buffer } from "node:buffer";
+export * from "./http-headers.mjs";
+export * from "./http-codes.mjs";
+import { EventEmitter } from "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;
+};
+
+export { DeclarativeResponse, extendApp, registerAbort, toAB, closure };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ublitzjs/core",
+  "version": "0.0.1",
+  "exports": {
+    "types": "./types/index.d.ts",
+    "require": "./cjs/index.cjs",
+    "import": "./mjs/index.mjs"
+  },
+  "dependencies": {
+    "tseep": "^1.3.1",
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.52.0"
+  },
+  "publishConfig": {"access": "public"},
+  "devDependencies": {
+    "undici": "^7.10.0",
+    "esbuild": "^0.25.4",
+    "vitest": "^3.1.1",
+    "ws": "^8.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ublitzjs/core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ublitzjs/core/issues",
+    "email": "diril656@gmail.com"
+  },
+  "homepage": "https://github.com/ublitzjs/core#readme"
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "esnext",
+    "moduleDetection": "force",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "skipLibCheck": false,
+    "noLib": false,
+    // Best practices
+    "strict": true,
+    "alwaysStrict": true,
+    "noFallthroughCasesInSwitch": true,
+    "removeComments": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": true,
+    "allowUnusedLabels": false,
+    "strictBuiltinIteratorReturn": true,
+    "strictBindCallApply": true,
+    "noUnusedParameters": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "strictPropertyInitialization": true,
+    "strictFunctionTypes": true,
+    "allowUnreachableCode": false,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/types/http-codes.d.ts

@@ -0,0 +1,54 @@
+import type { HttpResponse as uwsHttpResponse } from "uWebSockets.js";
+import type { HttpRequest, HttpMethods } from ".";
+/**
+ * If something wrong is to content-length, sends 411 code and throws error with a "cause"
+ */
+export function checkContentLength(
+  res: uwsHttpResponse,
+  req: HttpRequest
+): number;
+/**
+ * sends http 400 and throws an Error with "causeForYou"
+ */
+export function badRequest(
+  res: uwsHttpResponse,
+  error: string,
+  causeForYou: string
+): void;
+/**
+ * sends http 413 And throws, but doesn't throw an Error
+ */
+export function tooLargeBody(res: uwsHttpResponse, limit: number): void;
+/**
+ * Constructs function, which sends http 405 and sets http Allow header with all methods you passed
+ */
+export function seeOtherMethods(
+  methodsArr: HttpMethods[]
+): (res: uwsHttpResponse, req: any) => any;
+
+/**
+ * Constructs the function, which sets 404 http code and sends the message you have specified
+ */
+export function notFoundConstructor(
+  message?: string
+): (res: uwsHttpResponse, req: any) => any;
+/**
+ * code: required content length
+ */
+export var c411: ArrayBuffer;
+/**
+ * code: bad request
+ */
+export var c400: ArrayBuffer;
+/**
+ * code: payload too large
+ */
+export var c413: ArrayBuffer;
+/**
+ * code: method not allowed
+ */
+export var c405: ArrayBuffer;
+/**
+ * code: not found
+ */
+export var c404: ArrayBuffer;

package/types/http-headers.d.ts

@@ -0,0 +1,285 @@
+import type { HttpResponse } from "./index";
+import type { HttpResponse as uwsHttpResponse } from "uWebSockets.js";
+type helmetHeadersT = {
+  /**
+   * if client fetched resource, but its MIME type is different - abort request
+   */
+  "X-Content-Type-Options": "nosniff";
+  /**
+   * Safari doesn't support it
+   */
+  "X-DNS-Prefetch-Control": "on" | "off";
+  /**
+   * Sites can use this to avoid clickjacking (<iframe> html tag)
+   */
+  "X-Frame-Options": "DENY" | "SAMEORIGIN";
+  /**
+   * whether you need info about client.
+   */
+  "Referrer-Policy":
+    | "no-referrer"
+    | "no-referrer-when-downgrade"
+    | "origin"
+    | "origin-when-cross-origin"
+    | "same-origin"
+    | "strict-origin"
+    | "strict-origin-when-cross-origin"
+    | "unsafe-url";
+  /**
+   * usually for Adobe Acrobat or Microsoft Silverlight.
+   */
+  "X-Permitted-Cross-Domain-Policies":
+    | "none"
+    | "master-only"
+    | "by-content-type"
+    | "by-ftp-filename"
+    | "all"
+    | "none-this-response";
+  /**
+   * Whether downloaded files should be run on the client side immediately. For IE8
+   */
+  "X-Download-Options": "noopen";
+  /**
+   * From where should client fetch resources
+   */
+  "Cross-Origin-Resource-Policy": "same-site" | "same-origin" | "cross-origin";
+  /**
+   * whether new page opened via Window.open() should be treated differently for performance reasons
+   */
+  "Cross-Origin-Opener-Policy":
+    | "unsafe-none"
+    | "same-origin-allow-popups"
+    | "same-origin"
+    | "noopener-allow-popups";
+  /**
+   *  By adding this header you can declare that your site should only load resources that have explicitly opted-in to being loaded across origins.
+   * "require-corp" LETS YOU USE new SharedArrayBuffer()
+   */
+  "Cross-Origin-Embedder-Policy":
+    | "unsafe-none"
+    | "require-corp"
+    | "credentialless";
+  /**
+   * similar to COOP, where ?1 is true
+   */
+  "Origin-Agent-Cluster": "?0" | "?1";
+};
+type allHeaders = {
+  /**
+   * Headers, which may change for different responses. Use the same value for all methods of a given url.
+   * @example
+   * "Content-Type, Content-Length"
+   */
+  Vary: string;
+  /**
+   * confirms that client "really wants" to request that an HTTP client is upgraded to become a WebSocket.
+   */
+  "Sec-Websocket-Key": string;
+  /**
+   * protocol you are communicating by using WebSockets
+   * @see https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name
+   */
+  "Sec-Websocket-Protocol": string;
+  "Sec-Websocket-Extensions": string;
+  Server: string;
+  "Set-Cookie": string;
+  Upgrade: string;
+  "User-Agent": string;
+  Origin: string;
+  Range: string;
+  Location: string;
+  "Last-Modified": string;
+  Host: string;
+  Forwarded: string;
+  Cookie: string;
+  Allow: string;
+  "Access-Control-Request-Headers": string;
+  "Access-Control-Request-Method": string;
+  /**
+   * indicates which content types, expressed as MIME types, the sender is able to understand
+   */
+  Accept: string;
+  /**
+   * You know this one. It is "text/html" or "video/mp4" or whatever
+   */
+  "Content-Type": string;
+  /**
+   * Length in bytes of content, you send or receive.
+   * @type number. BUT here it is a string
+   */
+  "Content-Length": string;
+  /**
+   * get it from setCSP()
+   */
+  "Content-Security-Policy": string;
+  //"Content-Security-Policy-Report-Only":"",
+  //"Strict-Transport-Security":`max-age=${60 * 60 * 24 * 365}; includeSubDomains`,
+  /**
+   * Allowed origins to get the resource. * - all, https://example.com - some website.
+   */
+  "Access-Control-Allow-Origin": string;
+  /**
+   * Allowed headers in the request.
+   */
+  "Access-Control-Allow-Headers": string;
+  /**
+   * CORS version of Allow header
+   */
+  "Access-Control-Allow-Methods": string;
+  /**
+   * How much time the response should be cached.
+   * 1) must-revalidate
+   * 2) no-cache
+   * 3) no-store
+   * 4) no-transform
+   * 5) public -> cached anyhow
+   * 6) private
+   * 7) proxy-revalidate
+   * 8) max-age=<seconds>
+   * 9) s-maxage=<seconds>;
+   * @but those below aren't supported everywhere:
+   * 1) immutable
+   * 2) stale-while-revalidate=<seconds>
+   * 3) stale-if-error=<seconds>
+   */
+  "Cache-Control": string;
+  "Access-Control-Max-Age": string;
+};
+export type BaseHeaders = Partial<
+  allHeaders & helmetHeadersT & { [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) As a default use HeadersMap.default. It can't be edited, because it is already "prepared".
+ * 4) Don't define them before writing status on request. uWebSockets.js after first written header considers response 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).
+ */
+export class HeadersMap<Opts extends BaseHeaders> extends Map {
+  public currentHeaders: undefined | Opts;
+  constructor(opts: Opts);
+  /**
+   * remove several headers from this map. Use BEFORE map.prepare(), because it will compare them by location in memory (string !== ArrayBuffer)
+   * @example HeadersMap.default.remove("Content-Security-Policy", "X-DNS-Prefetch-Control", ...otherHeaders).prepare()
+   */
+  remove(...keys: (keyof Opts)[]): this;
+  /**
+   * last function before "going to response". It converts all strings to ArrayBuffers, so you should delete unwanted headers before it
+   * @returns function, which sets all headers on the response.
+   * @example
+   * new HeadersMap({...HeadersMap.baseObj,"a":"a"}).remove("a").prepare();
+   */
+  prepare(): (res: uwsHttpResponse) => HttpResponse;
+  /**
+   * write all static headers to response. Use AFTER map.prepare function, if you want speed.
+   * @example
+   * headersMap.toRes(res);
+   * // if you want dynamic headers, use BASE:
+   * res.writeHeader(toAB(headerVariable),toAB(value))
+   */
+  toRes(res: uwsHttpResponse): HttpResponse;
+
+  /**
+   * obj, containing basic headers, which u can use as a background for own headers
+   * @example
+   * new HeadersMap({...HeadersMap.baseObj, "ownHeader":"hello world"}).remove("X-Download-Options")
+   */
+  static baseObj: helmetHeadersT;
+  /**
+   * map with default headers
+   */
+  static default: (res: uwsHttpResponse) => HttpResponse;
+}
+/**
+ * This function creates Content-Security-Policy string.
+ */
+export function setCSP<T extends CSP>(
+  mainCSP: T,
+  ...remove: (keyof CSP)[]
+): string;
+type CSP = Partial<
+  typeof CSPDirs & {
+    /**
+     * for websites with deprecated urls.
+     */
+    "upgrade-insecure-requests": string[];
+  }
+>;
+/**
+ * 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: {
+  /**
+   * basic urls for resources, if other directives are missing
+   */
+  "default-src": string[];
+  /**
+   *used for html <base> tag
+   */
+  "base-uri": string[];
+  /**
+   * urls valid for css at-rule @font-face
+   */
+  "font-src": string[];
+  /**
+   * urls, allowed for <form action=""> action attribute. Forbidden at all='none'
+   */
+  "form-action": string[];
+  /**
+   * urls of sites, WHICH can embed YOUR page via <iframe> etc. 'none' = forbidden at all
+   */
+  "frame-ancestors": string[];
+  /**
+   * valid image urls. 'none' = forbidden at all
+   */
+  "img-src": string[];
+  /**
+   * controls urls of WebSocket, fetch, fetchLater, EventSources and Navigator.sendBeacon functions or ping attribute of <a> tag.
+   */
+  "connect-src": string[];
+  /**
+   * usually stuff it has influence on is deprecated, so put 'none'
+   */
+  "object-src": string[];
+  /**
+   * Urls for script tags. But also it forbids inline js scripts. 'none' - forbidden, 'self' - your site's scripts, 'unsafe-inline' - allows inline scripts
+   */
+  "script-src": string[];
+  /**
+   * More important than "script-src", specifies inline js scripts. 'unsafe-inline' - allow onclick and other inline attributes
+   */
+  "script-src-attr": string[];
+  /**
+   * More important than "script-src", specifies urls for <script> tag. 'none' - forbidden; 'unsafe-inline' - allow <script> tag without src=""; 'unsafe-eval' - for protobufjs;
+   */
+  "script-src-elem": string[];
+  /**
+   * Urls for style tags. But also it forbids inline css styles. 'none' - forbidden, 'self' - your site's styles, 'unsafe-inline' - allows inline styles
+   */
+  "style-src": string[];
+  /**
+   * More important than "style-src", specifies inline css styles.
+   */
+  "style-src-attr": string[];
+  /**
+   * More important than "style-src", specifies urls for <link> tag
+   */
+  "style-src-elem": string[];
+  /**
+   * Trusted Types XSS DOM API names. 'allow-duplicates', 'none'. Works for Chrome and Edge.
+   */
+  "trusted-types": string[];
+  /**
+   * specifies valid sources for Worker, SharedWorker, or ServiceWorker scripts.
+   */
+  "worker-src": string[];
+  /**
+   * specifies valid sources for loading media using the <audio> and <video> elements.
+   */
+  "media-src": string[];
+};
+export type lowHeaders = Lowercase<keyof allHeaders>;

package/types/index.d.ts

@@ -0,0 +1,170 @@
+import type {
+  HttpRequest as uwsHttpRequest,
+  TemplatedApp,
+  HttpResponse as uwsHttpResponse,
+  RecognizedString,
+  us_socket_context_t,
+} from "uWebSockets.js";
+import { Buffer } from "node:buffer";
+
+import { EventEmitter } from "tseep";
+import type { DocumentedWSBehavior } from "./uws-types";
+/**
+ * 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)
+ * @param res
+ */
+export function registerAbort(res: uwsHttpResponse): HttpResponse;
+/**
+ * An extended version of uWS.App . It provides you with several features:
+ * 1) plugin registration (just like in Fastify);
+ * 2) "ready" function and _startPromises array (use it to make your code more asynchronous and safe)
+ * 3) "route" function for more descriptive adn extensible way of registering handlers
+ * 4) "onError" function (mainly used by @ublitzjs/router)
+ */
+export interface Server extends TemplatedApp {
+  /**
+   * It is same as plugins in Fastify -> you register some routes in remove file
+   * @param plugin
+   * @returns itself for chaining methods
+   */
+  register(plugin: (server: this) => void): this;
+  /** set global _errHandler (in fact it is used only by @ublitzjs/router) */
+  onError(fn: (error: Error, res: HttpResponse, data: any) => any): this;
+  _errHandler?(error: Error, res: HttpResponse, data: any): any;
+  /**some undocumented property in uWS - get it here */
+  addChildAppDescriptor(...any: any[]): this;
+  /**a function, which awaits all promises inside _startPromises array and then clears it*/
+  ready: () => Promise<any[]>;
+  /**
+   * simple array of promises. You can push several inside and await all of them using server.ready() method
+   */
+  _startPromises: Promise<any>[];
+  /**
+   * this function allows you to create new handlers but more dynamically than uWS. Best use case - development. By default, the first param you pass includes a method, path, and a controller. However you can configure it for additional properties, which can be consumed on startup by second param - plugins
+   * @example
+   * server.route<onlyHttpMethods, {deprecated:boolean}>({
+   *   method:"any",
+   *   path: "/",
+   *   controller(res){ res.end("hello") },
+   *   deprecated:true
+   * },
+   * [
+   *   (opts)=>{
+   *     if(opts.deprecated) console.error("DEPRECATION FOUND", opts.path)
+   *   }
+   * ])
+   */
+  route<T extends HttpMethods, obj extends object = {}>(
+    opts: routeFNOpts<T> & obj,
+    plugins?: ((param: typeof opts, server: this) => void)[]
+  ): this;
+  get(pattern: RecognizedString, handler: HttpControllerFn): this;
+  post(pattern: RecognizedString, handler: HttpControllerFn): this;
+  options(pattern: RecognizedString, handler: HttpControllerFn): this;
+  del(pattern: RecognizedString, handler: HttpControllerFn): this;
+  patch(pattern: RecognizedString, handler: HttpControllerFn): this;
+  put(pattern: RecognizedString, handler: HttpControllerFn): this;
+  head(pattern: RecognizedString, handler: HttpControllerFn): this;
+  connect(pattern: RecognizedString, handler: HttpControllerFn): this;
+  trace(pattern: RecognizedString, handler: HttpControllerFn): this;
+  any(pattern: RecognizedString, handler: HttpControllerFn): this;
+}
+export type routeFNOpts<T extends HttpMethods> = {
+  method: T;
+  path: RecognizedString;
+  controller: T extends "ws" ? DocumentedWSBehavior<any> : HttpControllerFn;
+};
+
+/**
+ * Utility for making closures. Exists for organizing code and caching values in non-global scope.
+ * @param param
+ * @returns what you passed
+ */
+export var closure: <T>(param: () => T) => T;
+/**
+ * little more typed response which has:
+ * 1) "emitter", that comes from "tseep" package
+ * 2) "aborted" flag
+ * 3) "finished" flag
+ * 4) "collect" function, which comes from original uWS (and isn't documented), but the purpose remains unknown
+ */
+export interface HttpResponse<UserDataForWS extends object = {}>
+  extends uwsHttpResponse {
+  upgrade<UserData = UserDataForWS>(
+    userData: UserData,
+    secWebSocketKey: RecognizedString,
+    secWebSocketProtocol: RecognizedString,
+    secWebSocketExtensions: RecognizedString,
+    context: us_socket_context_t
+  ): void;
+  /**
+   * This method actually exists in original uWebSockets.js, but is undocumented. I'll put it here for your IDE to be happy
+   */
+  collect: (...any: any[]) => any;
+  /**
+   * An event emitter, which lets you subscribe several listeners to "abort" event OR your own events, defined with Symbol().
+   */
+  emitter: EventEmitter<{
+    abort: () => void;
+    [k: symbol]: (...any: any[]) => void;
+  }>;
+  /**
+   * changes when res.onAborted fires.
+   */
+  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.
+   */
+  finished: boolean;
+}
+/**This HttpRequest is same as original uWS.HttpRequest, but getHeader method is typed for additional tips
+ * @example
+ * import {lowHeaders} from "ublitzjs"
+ * // some handler later
+ * req.getHeader<lowHeaders>("content-type")
+ */
+export interface HttpRequest extends uwsHttpRequest {
+  getHeader<T extends RecognizedString = RecognizedString>(a: T): string;
+}
+
+export type HttpControllerFn = (
+  res: HttpResponse,
+  req: HttpRequest
+) => any | Promise<any>;
+/**
+ * only http methods without "ws"
+ */
+export type onlyHttpMethods =
+  | "get"
+  | "post"
+  | "del"
+  | "patch"
+  | "put"
+  | "head"
+  | "trace"
+  | "options"
+  | "connect"
+  | "any";
+/**
+ * all httpMethods with "ws" method
+ */
+export type HttpMethods = onlyHttpMethods | "ws"; //NOT A HTTP METHOD, but had to put it here
+type MergeObjects<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? First & MergeObjects<Rest extends any[] ? Rest : []>
+  : {};
+/**
+ * extends uWS.App() or uWS.SSLApp. See interface Server
+ * @param app uWS.App()
+ */
+export function extendApp<T extends object[]>(
+  app: TemplatedApp,
+  ...rest: T
+): Server & MergeObjects<T>;
+/**
+ * conversion to ArrayBuffer ('cause transferring strings to uWS is really slow)
+ */
+export function toAB(data: Buffer | string): ArrayBuffer;
+
+export * from "./http-headers";
+export * from "./http-codes";
+export * from "./uws-types";