lightpress 1.1.0 → 2.0.0-beta.1

package/README.md

@@ -1,196 +1,132 @@
 # lightpress
 
-Lightpress is a thin wrapper around node's HTTP handler interface, that enables
-you to
-
-- compose a handler tree without overhead
-- write reusable and easy-to-test handler functions
-
-Although you can use lightpress for any kind of application, it was designed
-with modern API driven web applications in mind. These usually require a single
-handler for serving the (SSR) HTML content, another one for static assets, and
-one or more handlers for data.
+Lightpress is a thin wrapper around Node's HTTP request event, providing a composable HTTP handler interface.
 
 ## Installation
 
-You can install lightpress from [npmjs.com](https://www.npmjs.com) using your
-favorite package manager, e.g.
-
 ```bash
-$ npm install --save lightpress
+npm add lightpress
 ```
 
-## Getting Started
-
-In lightpress a request handler is a plain function that takes a context object
-as single argument and returns a result or a promise that resolves to a result.
-
-By default, the context object only contains a reference to the incoming
-request, but can be augmented to your application's needs.
+## Basic Usage
 
-The handler's outcome, if any, has to be an object that might contain a
-`statusCode`, `headers` and a `body`.
+Create an HTTP handler function that receives a Node.js `IncomingMessage` and returns a result:
 
 ```js
 import { createServer } from "http";
-import lightpress from "lightpress";
+import { createRequestListener } from "lightpress";
 
-function hello(context) {
+function greet(request) {
   return {
     statusCode: 200,
-    headers: {
-      "Content-Type": "text/plain",
-    },
-    body: `Hello from '${context.request.url}'.`,
+    headers: { "Content-Type": "text/plain" },
+    body: `Hello from '${request.url}'.`,
   };
 }
 
-const server = createServer(lightpress(hello));
-server.listen(8080);
+createServer(
+  createRequestListener(greet)
+).listen(8080);
 ```
 
 ## Composing Handlers
 
-Putting everything into a single handler isn't sufficient. And the way
-lightpress solves this circumstance is by composing its handlers.
-
-Lets imagine, the `hello` handler from above must only be called for `GET`
-requests. To achieve this we could simply check the request method inside our
-`hello` handler. However, a better approach is to create a separate
-handler which only cares about request methods.
+You can compose handlers for more control. For example, you can restrict allowed HTTP methods.
 
 ```js
-import lightpress, { HttpError } from "lightpress";
-
-// ...
+import { HttpError } from "lightpress";
 
 function allowedMethods(methods, handler) {
-  return (context) => {
-    if (methods.includes(context.request.method)) {
-      return handler(context);
+  return (request) => {
+    if (methods.includes(request.method)) {
+      return handler(request);
     }
-
     throw new HttpError(405);
   };
 }
 
-// ...
-
-const server = createServer(lightpress(allowedMethods(["GET"], hello)));
+createServer(
+  createRequestListener(
+    allowedMethods(["GET"], greet)
+  )
+).listen(8080);
 ```
 
-The `allowedMethods` function is a factory that takes an array of allowed HTTP
-methods and a handler. It creates a new handler that will invoke the given one
-only if the method of the incoming request is included in the array of allowed
-methods. Otherwise, a `Method Not Allowed` error is thrown.
-
 ## Error Handling
 
-In lightpress, errors are handled using guards. A guard itself is just another
-handler that catches the error that was thrown from the inner handler and
-converts it to a result. As with any other handler, guards can be nested, giving
-you fine grained control on how the error flows.
+Lightpress supports flexible error handling at multiple levels. You can create special HTTP handlers that act as error guards. These guards allow you to control how specific parts of your handler tree respond to errors. For example, a guard around your rendering code could send errors as HTML, while a guard around your API could return JSON responses.
 
 ```js
-// ...
-
-function catchError(handler) {
-  return (context) =>
-    new Promise((resolve) => resolve(handler(context))).catch((error) => {
-      const statusCode = error instanceof HttpError ? error.statusCode : 500;
-      const message =
-        statusCode === 405 ? "Better watch your verbs." : "My bad.";
-      const body = Buffer.from(message);
-
-      return {
-        headers: {
-          "Content-Type": "text/plain",
-          "Content-Length": body.length,
-        },
-        statusCode,
-        body,
-      };
-    });
+import { HttpError } from "lightpress";
+
+async function errorGuard(handler: HttpHandler) {
+  try {
+    return await handler(request);
+  } catch (error) {
+     // Handle the error and return a result or re-throw the error
+    // to be handled by an upper guard.
+  }
 }
-
-// ...
-
-const server = createServer(
-  lightpress(catchError(allowedMethods(["GET"], hello)))
-);
 ```
 
-If an error is not handled, lightpress will catch it and send a basic error
-response without content.
-
-## Custom Data
-
-The context object that is passed to a handler can be augmented with custom
-data. Although it is technically possible to create a new copy of that context
-object whenever you pass it on to the next handler, you most likely won't need
-that. In fact, some 3rd-party packages might rely on using the same reference
-and could break when creating a copy.
-
-The recommended way to augement the context object, is by providing a handler
-function that manipulates the context object. And another function that savely
-returns the desired data from the context object. Or provides a fallback.
-
-The following function adds a simple `log` function to the context object.
+Additionally, any `HttpError` that reaches Lightpress’s root handler is considered a handled error and will be sent as an HTTP response. The `HttpError` constructor can receive either a status code or a full `HttpResult` object.
 
 ```js
-function injectLogger(handler) {
-  return (context) => {
-    const { method, url } = context.request;
-
-    context.log = (message) => `${new Date()} [${method} ${url}]: ${message}`;
-
-    return handler(context);
-  };
-}
+// Only status code
+throw new HttpError(404);
+
+// With full HTTP result
+throw new HttpError({
+  statusCode: 404,
+  headers: { "Content-Type": "text/plain" },
+  body: "Not found",
+});
 ```
 
-The `log` function can be retrieved from the context using the following
-function.
+Any other error is considered unexpected, and Lightpress will therefore respond with a generic `500` error. However, you can pass a `recover` function to `createRequestListener` as a second argument for global error handling.
 
 ```js
-function extractLogger(context) {
-  if (context.log) {
-    return context.log;
-  }
-
-  console.warn("Trying to access logger, but was not injected.");
+function recover(request, error) {
+  // Use this to run some cleanup code or do some logging.
 
-  return () => void 0;
+  return {
+    statusCode: 500,
+    headers: { "Content-Type": "text/plain" },
+    body: "Internal Server Error",
+  };
 }
-```
-
-If no `log` function was injected into the context object, a warning is
-printed and a `noop`-fallback is return instead.
 
-```js
-//  ...
+createServer(
+  createRequestListener(greet, recover)
+).listen(8080);
+```
 
-function hello(context) {
-  const log = extractLogger(context);
+## Handler Factories
 
-  log("Serving request from hello handler.");
+In real-world applications, it’s common to provide an HTTP handler by using a configurable factory. A factory can receive options, such as a database connection or other configuration, and returns an HTTP handler. This helps to decouple infrastructure from business logic and allows for simpler code reuse.
 
-  return {
-    statusCode: 200,
-    headers: {
-      "Content-Type": "text/plain",
-    },
-    body: `Hello from '${context.request.url}'.`,
+```js
+function createApiHandler({ db }) {
+  return async (request) => {
+    const data = await db.getSomeData();
+    
+    return {
+      statusCode: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(data),
+    };
   };
 }
 
-// ...
-
-const server = createServer(
-  lightpress(injectLogger(catchError(allowedMethods(["GET"], hello))))
-);
+createServer(
+  createRequestListener(
+    createApiHandler({ db })
+  )
+).listen(8080);
 ```
 
-Just like with error handlers, you have the exact same control when to extend
-the context object. This lets you for example inject a `user` right before your
-API handler is called, but ignore it for all sibling handlers.
+## Custom Handler Types and Context
+
+Lightpress’s handler type is intentionally simple: it expects a function that receives a Node.js `IncomingMessage` and returns a result. Depending on your application, your HTTP handler may need additional request-related context, such as a timestamp, a user, or data that is expensive to retrieve. In this case, you will likely want to define your own handler type.
+
+_TODO: add example_

package/lib/create-request-listener.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from "node:http";
+/** An object that is used to be send as HTTP response. */
+export type HttpResult = null | undefined | {
+    /** Optional response status code (defaults to `200`). */
+    statusCode?: null | number;
+    /** Optional response body. */
+    body?: null | string | Buffer | NodeJS.ReadableStream;
+    /** Optional HTTP response headers. */
+    headers?: null | OutgoingHttpHeaders;
+};
+/** An HTTP request handler that creates an {@link HttpResult}. */
+export type HttpHandler = (request: IncomingMessage) => HttpResult | Promise<HttpResult>;
+/** A handler to recover from unhandled errors by the {@link HttpHandler}. */
+export type RecoverHandler = (request: IncomingMessage, error: unknown) => HttpResult | Promise<HttpResult>;
+/** Wraps an {@link HttpHandler} and returns a NodeJS request listener. */
+export declare function createRequestListener(handler: HttpHandler, recover?: RecoverHandler): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/lib/create-request-listener.js

@@ -0,0 +1,27 @@
+import { sendResult } from "./send-result";
+import { HttpError } from "./http-error";
+/** Wraps an {@link HttpHandler} and returns a NodeJS request listener. */
+export function createRequestListener(handler, recover) {
+    if (typeof handler !== "function") {
+        throw new TypeError("request handler must be a function");
+    }
+    return (request, response) => new Promise((resolve) => resolve(handler(request)))
+        .catch((error) => {
+        // Instances of `HttpError` are send as response, all other error types
+        // are considered unhandled.
+        if (error instanceof HttpError) {
+            return error;
+        }
+        if (recover) {
+            return recover(request, error);
+        }
+        throw error;
+    })
+        .catch((error) => {
+        // Log unhandled error if no recover handler is defined or an error was
+        // thrown from the recover handler itself.
+        console.error(error);
+        return { statusCode: 500 };
+    })
+        .then((result) => sendResult(response, result));
+}

package/lib/http-error.d.ts

@@ -1,14 +1,11 @@
-import { LightpressError } from "./types/lightpress-error";
-import { LightpressResult } from "./types/lightpress-result";
-/** Basic error implementation to signal HTTP errors. */
-export declare class HttpError extends Error implements LightpressError {
-    readonly name: string;
-    readonly statusCode: number;
-    /**
-     * The HTTP error represents an error based on the HTTP error codes.
-     * @param statusCode An HTTP status code
-     */
-    constructor(statusCode: number);
-    /** Converts the error to an HTTP result object. */
-    toResult(): LightpressResult;
+import type { OutgoingHttpHeaders } from "node:http";
+import type { HttpResult } from "./create-request-listener";
+/** An error that can be send as an HTTP result. */
+export declare class HttpError extends Error implements NonNullable<HttpResult> {
+    name: string;
+    statusCode: number;
+    body?: null | string | Buffer | NodeJS.ReadableStream;
+    headers?: null | OutgoingHttpHeaders;
+    constructor(result: HttpResult, options?: ErrorOptions);
+    constructor(statusCode: number, options?: ErrorOptions);
 }

package/lib/http-error.js

@@ -0,0 +1,21 @@
+import { STATUS_CODES } from "node:http";
+/** An error that can be send as an HTTP result. */
+export class HttpError extends Error {
+    name = "HttpError";
+    statusCode;
+    body;
+    headers;
+    constructor(resultOrStatusCode, options) {
+        const [statusCode, result] = typeof resultOrStatusCode === "number"
+            ? [resultOrStatusCode, null]
+            : [resultOrStatusCode?.statusCode ?? 500, resultOrStatusCode];
+        super(STATUS_CODES[statusCode], options);
+        // TODO: investigate if this is really needed
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        this.statusCode = statusCode;
+        this.body = result?.body;
+        this.headers = result?.headers;
+    }
+}

package/lib/index.d.ts

@@ -1,10 +1,3 @@
-export * from "./types/lightpress-context";
-export * from "./types/lightpress-error";
-export * from "./types/lightpress-handler";
-export * from "./types/lightpress-recovery-handler";
-export * from "./types/lightpress-result";
-export * from "./from-lightpress-error";
+export * from "./create-request-listener";
 export * from "./http-error";
-export * from "./is-lightpress-error";
-export * from "./lightpress";
-export { lightpress as default } from "./lightpress";
+export { createRequestListener as default } from "./create-request-listener";

package/lib/index.js

@@ -1,143 +1,3 @@
-'use strict';
-
-Object.defineProperty(exports, '__esModule', { value: true });
-
-var http = require('http');
-
-/**
- * Typeguard to test if the given object implements the `LightpressError`
- * interface.
- */
-function isLightpressError(error) {
-  return Boolean(error && typeof error.toResult === "function");
-}
-
-/**
- * Wraps a recover function to automatically recover from `LightpressError`s by
- * calling `toResult()` on it. All other errors are passed on to the given
- * recover function.
- * **WARNING:** does not catch errors from the recover function itself!
- */
-function fromLightpressError(
-  recoverUnhandled
-) {
-  return (request, error) => {
-    if (isLightpressError(error)) {
-      try {
-        return error.toResult();
-      } catch (exception) {
-        return recoverUnhandled(request, exception);
-      }
-    } else {
-      return recoverUnhandled(request, error);
-    }
-  };
-}
-
-/** Basic error implementation to signal HTTP errors. */
-class HttpError extends Error  {
-    __init() {this.name = "HttpError";}
-  
-
-  /**
-   * The HTTP error represents an error based on the HTTP error codes.
-   * @param statusCode An HTTP status code
-   */
-   constructor(statusCode) {
-    super(http.STATUS_CODES[statusCode]);HttpError.prototype.__init.call(this);
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-
-    this.statusCode = statusCode;
-  }
-
-  /** Converts the error to an HTTP result object. */
-   toResult() {
-    return { statusCode: this.statusCode };
-  }
-}
-
-/** Typeguard to test if the given object is a readable stream. */
-function isReadableStream(data) {
-  return Boolean(
-    data &&
-      data.readable === true &&
-      typeof data.pipe === "function" &&
-      typeof data._read === "function"
-  );
-}
-
-/** Takes a `LightpressResult` and sends it as HTTP response. */
-function sendResult(
-  response,
-  result
-) {
-  const statusCode = result && result.statusCode ? result.statusCode : 200;
-  const headers = result && result.headers ? result.headers : null;
-  const body = result && result.body ? result.body : null;
-
-  if (headers) {
-    response.writeHead(statusCode, headers);
-  } else {
-    response.statusCode = statusCode;
-  }
-
-  if (isReadableStream(body)) {
-    body.pipe(response);
-  } else {
-    response.end(body);
-  }
-}
-
-/**
- * Wraps a `LightpressHandler` into a function that directly be bound as handler
- * for an HTTP server's incoming `request` events.
- */
-function lightpress(
-  handler,
-  recover
-) {
-  if (typeof handler !== "function") {
-    throw new TypeError("request handler must be a function");
-  }
-  if (recover && typeof recover !== "function") {
-    throw new TypeError("recovery handler must be a function");
-  }
-
-  // Although it requires a little bit more boilerplate code, it is expected
-  // that the given recover handler cares about `LightpressError`s itself. In
-  // total, this provides more control over the error recovery.
-  const innerRecover =
-    recover || fromLightpressError(() => ({ statusCode: 500 }));
-
-  return (request, response) =>
-    // Directly return the promise so that it's resolution can be tracked
-    // outside, e.g. in unit tests.
-    new Promise((resolve) => resolve(handler({ request })))
-      // Instead of the context object, the request is passed to the recovery
-      // handler as we cannot know if the reference to the context has changed
-      // during handler invokation. Assumably, it would lead to more confussion
-      // about possibly missing properties than it would help.
-      .catch((error) => innerRecover(request, error))
-      .then((result) => sendResult(response, result))
-      // Fallback guard to prevent the application to crash if error recovery
-      // or sending the response have failed.
-      .catch((error) => {
-        console.error(error);
-
-        try {
-          // TODO: investigate if closing the connection is a better option
-          request.pause();
-          response.end();
-        } catch (exception) {
-          console.error(exception);
-        }
-      });
-}
-
-exports.HttpError = HttpError;
-exports.default = lightpress;
-exports.fromLightpressError = fromLightpressError;
-exports.isLightpressError = isLightpressError;
-exports.lightpress = lightpress;
+export * from "./create-request-listener";
+export * from "./http-error";
+export { createRequestListener as default } from "./create-request-listener";

package/lib/is-readable-stream.d.ts

@@ -1,3 +1,2 @@
-/// <reference types="node" />
 /** Typeguard to test if the given object is a readable stream. */
 export declare function isReadableStream(data: any): data is NodeJS.ReadableStream;

package/lib/is-readable-stream.js

@@ -0,0 +1,6 @@
+/** Typeguard to test if the given object is a readable stream. */
+export function isReadableStream(data) {
+    return Boolean(data?.readable === true &&
+        typeof data?.pipe === "function" &&
+        typeof data?._read === "function");
+}

package/lib/send-result.d.ts

@@ -1,5 +1,4 @@
-/// <reference types="node" />
-import { ServerResponse } from "http";
-import { LightpressResult } from "./types/lightpress-result";
-/** Takes a `LightpressResult` and sends it as HTTP response. */
-export declare function sendResult(response: ServerResponse, result: LightpressResult): void;
+import type { ServerResponse } from "node:http";
+import type { HttpResult } from "./create-request-listener";
+/** Passes the given {@link HttpResult} to the given {@link ServerResponse}. */
+export declare function sendResult(response: ServerResponse, result: HttpResult): void;

package/lib/send-result.js

@@ -0,0 +1,17 @@
+import { isReadableStream } from "./is-readable-stream";
+/** Passes the given {@link HttpResult} to the given {@link ServerResponse}. */
+export function sendResult(response, result) {
+    const statusCode = result?.statusCode ?? 200;
+    if (result?.headers) {
+        response.writeHead(statusCode, result.headers);
+    }
+    else {
+        response.statusCode = statusCode;
+    }
+    if (isReadableStream(result?.body)) {
+        result.body.pipe(response);
+    }
+    else {
+        response.end(result?.body ?? null);
+    }
+}

package/lib/utility/assert-content-type.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingHttpHeaders, IncomingMessage } from "node:http";
+export declare function assertContentType<const TContentType extends string>(request: IncomingMessage, contentType: TContentType): asserts request is IncomingMessage & {
+    headers: IncomingHttpHeaders & {
+        ["content-type"]: TContentType;
+    };
+};

package/lib/utility/assert-content-type.js

@@ -0,0 +1,6 @@
+import { HttpError } from "../http-error";
+export function assertContentType(request, contentType) {
+    if (request.headers["content-type"] !== contentType) {
+        throw new HttpError(415);
+    }
+}

package/lib/utility/assert-method.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage } from "node:http";
+export declare function assertMethod<const TMethod extends string>(request: IncomingMessage, method: TMethod): asserts request is IncomingMessage & {
+    method: TMethod;
+};

package/lib/utility/assert-method.js

@@ -0,0 +1,6 @@
+import { HttpError } from "../http-error";
+export function assertMethod(request, method) {
+    if (request.method !== method) {
+        throw new HttpError(405);
+    }
+}

package/lib/utility/consume-body.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from "node:http";
+export declare function consumeBody(request: IncomingMessage, maxByteLength?: number): Promise<Buffer<ArrayBuffer>>;

package/lib/utility/consume-body.js

@@ -0,0 +1,15 @@
+import { HttpError } from "../http-error";
+export async function consumeBody(request, maxByteLength) {
+    const chunks = [];
+    let chunksBytes = 0;
+    for await (const chunk of request.iterator()) {
+        chunks.push(chunk);
+        chunksBytes = chunksBytes + chunk.byteLength;
+        if (maxByteLength && chunksBytes > maxByteLength) {
+            chunks.length = 0;
+            chunksBytes = 0;
+            throw new HttpError(413);
+        }
+    }
+    return Buffer.concat(chunks, chunksBytes);
+}

package/lib/utility/consume-json-body.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from "node:http";
+export declare function consumeJsonBody(request: IncomingMessage, maxByteLength?: number): Promise<any>;

package/lib/utility/consume-json-body.js

@@ -0,0 +1,13 @@
+import { HttpError } from "../http-error";
+import { consumeBody } from "./consume-body";
+export async function consumeJsonBody(request, maxByteLength) {
+    const buffer = await consumeBody(request, maxByteLength);
+    try {
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch (error) {
+        throw new HttpError(400, {
+            cause: error,
+        });
+    }
+}

package/lib/utility/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./assert-content-type";
+export * from "./assert-method";
+export * from "./consume-body";
+export * from "./consume-json-body";

package/lib/utility/index.js

@@ -0,0 +1,4 @@
+export * from "./assert-content-type";
+export * from "./assert-method";
+export * from "./consume-body";
+export * from "./consume-json-body";

package/package.json

@@ -1,54 +1,54 @@
 {
-  "name": "lightpress",
-  "version": "1.1.0",
-  "description": "Your composable HTTP server.",
-  "main": "lib/index.js",
-  "module": "lib/index.mjs",
-  "typings": "lib/index.d.ts",
-  "engines": {
-    "node": ">=12.0.0"
-  },
-  "scripts": {
-    "build": "rimraf $npm_package_directories_lib && rollup -c",
-    "develop": "rollup -c -w",
-    "format": "prettier --ignore-path .gitignore --write .",
-    "prepublishOnly": "npm run test && npm run build && npm run types",
-    "test": "jest",
-    "types": "tsc --emitDeclarationOnly"
-  },
-  "files": [
-    "lib/**/*"
-  ],
-  "directories": {
-    "lib": "lib"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lunsdorf/lightpress.git"
-  },
-  "keywords": [
-    "composable",
-    "express",
-    "http",
-    "lightpress",
-    "server"
-  ],
-  "license": "MIT",
-  "author": "Sören Lünsdorf <code@lunsdorf.com>",
-  "homepage": "https://github.com/lunsdorf/lightpress#readme",
-  "bugs": {
-    "url": "https://github.com/lunsdorf/lightpress/issues"
-  },
-  "devDependencies": {
-    "@rollup/plugin-sucrase": "3.1.0",
-    "@sucrase/jest-plugin": "2.0.0",
-    "@types/jest": "26.0.20",
-    "@types/node": "14.14.21",
-    "jest": "26.6.3",
-    "prettier": "2.2.1",
-    "rimraf": "3.0.2",
-    "rollup": "2.36.2",
-    "rollup-plugin-import-resolver": "1.0.5",
-    "typescript": "4.1.3"
-  }
+	"name": "lightpress",
+	"version": "2.0.0-beta.1",
+	"description": "A thin composable HTTP handler interface around NodeJS native server listener.",
+	"type": "module",
+	"typings": "lib/index.d.ts",
+	"main": "lib/index.js",
+	"exports": {
+		".": "./lib/index.js",
+		"./utility": "./lib/utility/index.js",
+		"./package.json": "./package.json"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"scripts": {
+		"build": "rimraf ./lib && tsc",
+		"check-format": "biome check .",
+		"check-types": "tsc --noEmit",
+		"format": "biome check --write .",
+		"prepublishOnly": "npm run check-format && npm run test && npm run build",
+		"test": "jest"
+	},
+	"files": [
+		"lib/**/*"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lunsdorf/lightpress.git"
+	},
+	"keywords": [
+		"composable",
+		"express",
+		"http",
+		"lightpress",
+		"server"
+	],
+	"license": "MIT",
+	"author": "Lunsdorf <lunsdorf@users.noreply.github.com>",
+	"homepage": "https://github.com/lunsdorf/lightpress#readme",
+	"bugs": {
+		"url": "https://github.com/lunsdorf/lightpress/issues"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.11",
+		"@swc/core": "^1.15.8",
+		"@swc/jest": "^0.2.39",
+		"@types/jest": "^30.0.0",
+		"@types/node": "^22.0.0",
+		"jest": "^30.2.0",
+		"rimraf": "^6.1.2",
+		"typescript": "^5.9.3"
+	}
 }

package/lib/from-lightpress-error.d.ts

@@ -1,8 +0,0 @@
-import { LightpressRecoveryHandler } from "./types/lightpress-recovery-handler";
-/**
- * Wraps a recover function to automatically recover from `LightpressError`s by
- * calling `toResult()` on it. All other errors are passed on to the given
- * recover function.
- * **WARNING:** does not catch errors from the recover function itself!
- */
-export declare function fromLightpressError(recoverUnhandled: LightpressRecoveryHandler): LightpressRecoveryHandler;

package/lib/index.mjs

@@ -1,136 +0,0 @@
-import { STATUS_CODES } from 'http';
-
-/**
- * Typeguard to test if the given object implements the `LightpressError`
- * interface.
- */
-function isLightpressError(error) {
-  return Boolean(error && typeof error.toResult === "function");
-}
-
-/**
- * Wraps a recover function to automatically recover from `LightpressError`s by
- * calling `toResult()` on it. All other errors are passed on to the given
- * recover function.
- * **WARNING:** does not catch errors from the recover function itself!
- */
-function fromLightpressError(
-  recoverUnhandled
-) {
-  return (request, error) => {
-    if (isLightpressError(error)) {
-      try {
-        return error.toResult();
-      } catch (exception) {
-        return recoverUnhandled(request, exception);
-      }
-    } else {
-      return recoverUnhandled(request, error);
-    }
-  };
-}
-
-/** Basic error implementation to signal HTTP errors. */
-class HttpError extends Error  {
-    __init() {this.name = "HttpError";}
-  
-
-  /**
-   * The HTTP error represents an error based on the HTTP error codes.
-   * @param statusCode An HTTP status code
-   */
-   constructor(statusCode) {
-    super(STATUS_CODES[statusCode]);HttpError.prototype.__init.call(this);
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-
-    this.statusCode = statusCode;
-  }
-
-  /** Converts the error to an HTTP result object. */
-   toResult() {
-    return { statusCode: this.statusCode };
-  }
-}
-
-/** Typeguard to test if the given object is a readable stream. */
-function isReadableStream(data) {
-  return Boolean(
-    data &&
-      data.readable === true &&
-      typeof data.pipe === "function" &&
-      typeof data._read === "function"
-  );
-}
-
-/** Takes a `LightpressResult` and sends it as HTTP response. */
-function sendResult(
-  response,
-  result
-) {
-  const statusCode = result && result.statusCode ? result.statusCode : 200;
-  const headers = result && result.headers ? result.headers : null;
-  const body = result && result.body ? result.body : null;
-
-  if (headers) {
-    response.writeHead(statusCode, headers);
-  } else {
-    response.statusCode = statusCode;
-  }
-
-  if (isReadableStream(body)) {
-    body.pipe(response);
-  } else {
-    response.end(body);
-  }
-}
-
-/**
- * Wraps a `LightpressHandler` into a function that directly be bound as handler
- * for an HTTP server's incoming `request` events.
- */
-function lightpress(
-  handler,
-  recover
-) {
-  if (typeof handler !== "function") {
-    throw new TypeError("request handler must be a function");
-  }
-  if (recover && typeof recover !== "function") {
-    throw new TypeError("recovery handler must be a function");
-  }
-
-  // Although it requires a little bit more boilerplate code, it is expected
-  // that the given recover handler cares about `LightpressError`s itself. In
-  // total, this provides more control over the error recovery.
-  const innerRecover =
-    recover || fromLightpressError(() => ({ statusCode: 500 }));
-
-  return (request, response) =>
-    // Directly return the promise so that it's resolution can be tracked
-    // outside, e.g. in unit tests.
-    new Promise((resolve) => resolve(handler({ request })))
-      // Instead of the context object, the request is passed to the recovery
-      // handler as we cannot know if the reference to the context has changed
-      // during handler invokation. Assumably, it would lead to more confussion
-      // about possibly missing properties than it would help.
-      .catch((error) => innerRecover(request, error))
-      .then((result) => sendResult(response, result))
-      // Fallback guard to prevent the application to crash if error recovery
-      // or sending the response have failed.
-      .catch((error) => {
-        console.error(error);
-
-        try {
-          // TODO: investigate if closing the connection is a better option
-          request.pause();
-          response.end();
-        } catch (exception) {
-          console.error(exception);
-        }
-      });
-}
-
-export default lightpress;
-export { HttpError, fromLightpressError, isLightpressError, lightpress };

package/lib/is-lightpress-error.d.ts

@@ -1,6 +0,0 @@
-import { LightpressError } from "./types/lightpress-error";
-/**
- * Typeguard to test if the given object implements the `LightpressError`
- * interface.
- */
-export declare function isLightpressError(error: any): error is LightpressError;

package/lib/lightpress.d.ts

@@ -1,10 +0,0 @@
-/// <reference types="node" />
-import { IncomingMessage, ServerResponse } from "http";
-import { LightpressContext } from "./types/lightpress-context";
-import { LightpressHandler } from "./types/lightpress-handler";
-import { LightpressRecoveryHandler } from "./types/lightpress-recovery-handler";
-/**
- * Wraps a `LightpressHandler` into a function that directly be bound as handler
- * for an HTTP server's incoming `request` events.
- */
-export declare function lightpress(handler: LightpressHandler<LightpressContext>, recover?: LightpressRecoveryHandler): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/lib/types/lightpress-context.d.ts

@@ -1,7 +0,0 @@
-/// <reference types="node" />
-import { IncomingMessage } from "http";
-/** Basic context object required by an HTTP handler to create a result. */
-export declare type LightpressContext = {
-    /** The incoming server request. */
-    request: IncomingMessage;
-};

package/lib/types/lightpress-error.d.ts

@@ -1,11 +0,0 @@
-import { LightpressResult } from "./lightpress-result";
-/**
- * Represents a handled error result that fits the dataflow of promises and can
- * be recoverd from.
- * NOTE: Intentionally, this is not designed as a common result factory as it
- * would make dataflow overly complicated and can already be archieved through
- * the use of promises itself.
- */
-export interface LightpressError extends Error {
-    toResult(): LightpressResult;
-}

package/lib/types/lightpress-handler.d.ts

@@ -1,7 +0,0 @@
-import { LightpressContext } from "./lightpress-context";
-import { LightpressResult } from "./lightpress-result";
-/**
- * Describes a function that creates a `LightpressResult` for incoming HTTP
- * requests.
- */
-export declare type LightpressHandler<T extends LightpressContext> = (context: T) => LightpressResult | Promise<LightpressResult>;

package/lib/types/lightpress-recovery-handler.d.ts

@@ -1,5 +0,0 @@
-/// <reference types="node" />
-import { IncomingMessage } from "http";
-import { LightpressResult } from "./lightpress-result";
-/** Describes a function to convert an error to a `LightpressResult`. */
-export declare type LightpressRecoveryHandler = (request: IncomingMessage, error: Error) => LightpressResult | Promise<LightpressResult>;

package/lib/types/lightpress-result.d.ts

@@ -1,11 +0,0 @@
-/// <reference types="node" />
-import { OutgoingHttpHeaders } from "http";
-/** An object that is used to be send as HTTP response. */
-export declare type LightpressResult = void | null | {
-    /** Optional response status code (defaults to `200`). */
-    statusCode?: null | number;
-    /** Optional response payload. */
-    body?: null | string | Buffer | NodeJS.ReadableStream;
-    /** Optional HTTP response headers. */
-    headers?: null | OutgoingHttpHeaders;
-};