cpeak 2.7.0 → 2.8.0

package/README.md

@@ -2,11 +2,15 @@
 
 [![npm version](https://badge.fury.io/js/cpeak.svg)](https://www.npmjs.com/package/cpeak)
 
-Cpeak is a minimal and fast Node.js framework inspired by Express.js.
+Cpeak is a minimal and fast Node.js framework inspired by Express.js & Fastify.
 
-This project is designed to be improved until it's ready for use in complex production applications, aiming to be more performant and minimal than Express.js. This framework is intended for HTTP applications that primarily deal with JSON and file-based message bodies.
+This project is designed to be improved until it's ready for use in complex production applications, aiming to be more performant and have a cleaner structure than Express.js and other common frameworks.
 
-This is an educational project that was started as part of the [Understanding Node.js: Core Concepts](https://www.udemy.com/course/understanding-nodejs-core-concepts/?referralCode=0BC21AC4DD6958AE6A95) course. If you want to learn how to build a framework like this, and get to a point where you can build things like this yourself, check out this course!
+Cpeak replaces Express.js, body-parser, cookie-parser, compression, CORS, Passport and more, in one zero-dependency package. You can use it as a drop-in replacement for Express.js, and many npm packages that work with Express.js will also work with Cpeak. 
+
+Cpeak currently has almost all the features of Express.js, with roughly the same performance as Fastify. Additionally, it has a codebase that you can easily navigate, audit and change if you want. *Benchmarks and test results, and videos on navigating and understanding the codebase will be added soon.*
+
+While Cpeak is being built for production, it is also an educational project that was started as part of the [Understanding Node.js: Core Concepts](https://www.udemy.com/course/understanding-nodejs-core-concepts/?referralCode=0BC21AC4DD6958AE6A95) course. If you want to learn how to build a framework like this, and get to a point where you can build things like this yourself and beyond, check out this course!
 
 ## Why Cpeak?
 
@@ -25,9 +29,11 @@ This is an educational project that was started as part of the [Understanding No
   - [Middleware](#middleware)
   - [Route Handling](#route-handling)
   - [Route Middleware](#route-middleware)
+  - [Fallback Handler](#fallback-handler)
   - [URL Variables & Parameters](#url-variables--parameters)
   - [Sending Files](#sending-files)
   - [Redirecting](#redirecting)
+  - [MIME Types](#mime-types)
   - [Compression](#compression)
   - [Error Handling](#error-handling)
   - [Listening](#listening)
@@ -60,7 +66,7 @@ import cpeak from "cpeak";
 const server = cpeak();
 
 server.route("get", "/", (req, res) => {
-  res.json({ message: "Hi there!" });
+  return res.json({ message: "Hi there!" });
 });
 
 server.listen(3000, () => {
@@ -127,13 +133,13 @@ server.beforeEach((req, res, next) => {
 You can also add middleware functions for a particular route handler like this:
 
 ```javascript
-const requireAuth = (req, res, next, handleErr) => {
+const requireAuth = (req, res, next) => {
   // Check if user is logged in, if so then:
   req.test = "this is a test value";
   next();
 
   // If user is not logged in:
-  return handleErr({ status: 401, message: "Unauthorized" });
+  throw { status: 401, message: "Unauthorized" };
 };
 
 server.route("get", "/profile", requireAuth, (req, res) => {
@@ -168,6 +174,20 @@ server.route("patch", "/the-path-you-want", (req, res) => {
 
 First add the HTTP method name you want to handle, then the path, and finally, the callback. The `req` and `res` object types are the same as in the Node.js HTTP module (`http.IncomingMessage` and `http.ServerResponse`). You can read more about them in the [official Node.js documentation](https://nodejs.org/docs/latest/api/http.html).
 
+Under the hood, Cpeak stores your routes in a radix tree, so finding the right route for an incoming request is roughly O(log n) in your total route count. In plain terms, that means matching stays fast even when your app has hundreds or thousands of routes. You won't pay a linear scan per request as your route table grows.
+
+### Fallback Handler
+
+If no route or middleware matches an incoming request, Cpeak returns a default `404` message. You can replace it with your own handler using `server.fallback`:
+
+```javascript
+server.fallback((req, res) => {
+  return res.status(404).json({ error: "not found" });
+});
+```
+
+Use this for custom 404 pages, JSON error envelopes, or serving an SPA's `index.html` for unknown paths. Static, param, and `*` wildcard routes still win when they match, the fallback only fires once the router has no match.
+
 ### URL Variables & Parameters
 
 To be more consistent with the broader Node.js community and frameworks, we call the HTTP URL parameters (query strings) '**query**', and the path variables (route parameters) '**params**'.
@@ -198,7 +218,15 @@ server.route("get", "/testing", (req, res) => {
 });
 ```
 
-The file’s binary content will be in the HTTP response body content. Make sure you specify a correct path relative to your CWD (use the `path` module for better compatibility) and also the correct HTTP MIME type for that file.
+The file’s binary content will be in the HTTP response body content. Make sure you specify a correct path relative to your CWD (use the `path` module for better compatibility).
+
+The MIME type argument is optional. When omitted, Cpeak infers it from the file extension using its built-in MIME registry (see [MIME Types](#mime-types)):
+
+```javascript
+return res.status(200).sendFile("./images/sun.jpeg");
+```
+
+Passing the MIME type explicitly is the fastest path, Cpeak skips the extension lookup entirely.
 
 ### Redirecting
 
@@ -208,6 +236,40 @@ If you want to redirect to a new URL, you can simply do:
 res.redirect("https://whatever.com");
 ```
 
+### MIME Types
+
+`serveStatic`, `res.sendFile`, and `res.render` all share a single MIME type registry. Out of the box it covers the common web types:
+
+```
+  html: "text/html",
+  css: "text/css",
+  js: "application/javascript",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  svg: "image/svg+xml",
+  gif: "image/gif",
+  ico: "image/x-icon",
+  txt: "text/plain",
+  json: "application/json",
+  webmanifest: "application/manifest+json",
+  eot: "application/vnd.ms-fontobject",
+  otf: "font/otf",
+  ttf: "font/ttf",
+  woff: "font/woff",
+  woff2: "font/woff2"
+```
+
+If you need to serve something else, register it once on the `cpeak()` constructor:
+
+```javascript
+const server = cpeak({
+  mimeTypes: { mp3: "audio/mpeg", m4a: "audio/mp4" }
+});
+```
+
+We keep this list small on purpose. Cpeak isn't going to load the [thousands of MIME types from the IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml) into your process memory on the off chance you might serve an `.apk` or a `.fla` one day. You tell us what you serve, we keep memory tight.
+
 ### Compression
 
 You can enable HTTP response compression at construction time. Once enabled, `serveStatic`, `res.json()` and `res.sendFile()` will compress eligible responses automatically, and you also get a `res.compress()` method on the response for custom payloads.
@@ -252,9 +314,7 @@ server.route("get", "/proxy/feed", async (req, res) => {
 });
 ```
 
-You must first enable compression at construction time to use `res.compress`. 
-
-One thing to keep in mind: when compression is enabled, `res.json()` returns a `Promise` because the work runs through async streams. You don't have to await it, but you can if you want to know when the response has been fully flushed.
+You must first enable compression at construction time to use `res.compress`.
 
 ### Error Handling
 
@@ -270,36 +330,40 @@ server.route("get", "/api/document/:title", (req, res) => {
 });
 ```
 
-You can also make use of the `handleErr` callback function like this:
-
-```javascript
-server.route("get", "/api/document/:title", (req, res, handleErr) => {
-  const title = req.params.title;
-
-  if (title.length > 500)
-    return handleErr({ status: 400, message: "Title too long." });
-
-  // The rest of your logic...
-});
-```
-
-**Make sure** to call the `server.handleErr` and pass a function like this to have the automatic error handler work properly:
+**Make sure** to call `server.handleErr` and pass a function like this to have the automatic error handler work properly:
 
 ```javascript
 server.handleErr((error, req, res) => {
   if (error && error.status) {
-    res.status(error.status).json({ error: error.message });
+    return res.status(error.status).json({ error: error.message });
   } else {
     // Log the unexpected errors somewhere so you can keep track of them...
     console.error(error);
-    res.status(500).json({
+    return res.status(500).json({
       error: "Sorry, something unexpected happened on our side."
     });
   }
 });
 ```
 
-_The error object is the object that you threw or passed to the `handleErr` function earlier in your routes._
+_The error object is the object that you threw earlier in your routes or middleware._
+
+One thing to keep in mind: `res.sendFile`, `res.render`, `res.compress`, and `res.json` all return a `Promise`. **Return** that promise (or `await` it in an `async` handler) so the framework can route any rejection to your `handleErr`:
+
+```javascript
+server.route("get", "/file", (req, res) => {
+  return res.sendFile("./images/sun.jpeg", "image/jpeg");
+});
+```
+
+Or, in an `async` handler that does other work alongside the send:
+
+```javascript
+server.route("get", "/avatars/:id", async (req, res) => {
+  const path = await db.lookupAvatarPath(req.params.id);
+  await res.sendFile(path);
+});
+```
 
 ### Listening
 
@@ -311,6 +375,8 @@ server.listen(3000, () => {
 });
 ```
 
+`server.listen` accepts the same arguments as Node.js's [http.Server.listen](https://nodejs.org/docs/latest/api/net.html#serverlistenoptions-callback), so you can also pass a host, an options object, or a Unix socket path.
+
 ### Util Functions
 
 There are utility functions that you can include and use as middleware functions. These are meant to make it easier for you to build HTTP applications. In the future, many more will be added, and you only move them into memory once you include them. No need to have many npm dependencies for simple applications!
@@ -336,44 +402,26 @@ import cpeak, { utilName } from "cpeak";
 With this middleware function, you can automatically set a folder in your project to be served by Cpeak. Here’s how to set it up:
 
 ```javascript
-server.beforeEach(
-  serveStatic("./public", {
-    mp3: "audio/mpeg"
-  })
-);
+server.beforeEach(serveStatic("./public"));
 ```
 
-If you have file types in your public folder that are not one of the following, make sure to add the MIME types manually as the second argument in the function as an object where each property key is the file extension, and each value is the correct MIME type for that. You can see all the available MIME types on the [IANA website](https://www.iana.org/assignments/media-types/media-types.xhtml).
-
-```
-  html: "text/html",
-  css: "text/css",
-  js: "application/javascript",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-  gif: "image/gif",
-  ico: "image/x-icon",
-  txt: "text/plain",
-  json: "application/json",
-  webmanifest: "application/manifest+json",
-  eot: "application/vnd.ms-fontobject",
-  otf: "font/otf",
-  ttf: "font/ttf",
-  woff: "font/woff",
-  woff2: "font/woff2"
-```
+`serveStatic` infers each file's MIME type from its extension. If your folder contains types that aren't in the built-in registry, register them on the `cpeak()` constructor (see [MIME Types](#mime-types)).
 
-You can also serve your static files under a URL prefix by passing a third argument with a `prefix` option. This is useful when you want all static assets to live under a specific path like `/static`:
+You can also serve your static files under a URL prefix by passing a `prefix` option. This is useful when you want all static assets to live under a specific path like `/static`:
 
 ```javascript
 server.beforeEach(
-  serveStatic("./public", null, { prefix: "/static" })
+  serveStatic("./public", { prefix: "/static" })
 );
 ```
 
-With this setup, a file at `./public/app.js` would be served at `/static/app.js` instead of `/app.js`. Pass `null` as the second argument if you don’t need any custom MIME types.
+With this setup, a file at `./public/app.js` would be served at `/static/app.js` instead of `/app.js`.
+
+If file names in the served folder change while the server is running (e.g. during development), pass `live: true` so the middleware stats the disk on each request instead of caching the file map at startup:
+
+```javascript
+server.beforeEach(serveStatic("./public", { live: true }));
+```
 
 #### parseJSON
 
@@ -395,7 +443,7 @@ server.route("put", "/api/user", (req, res) => {
   // rest of your logic...
 
   // Sending JSON in the HTTP response:
-  res.status(201).json({ message: "Something was created..." });
+  return res.status(201).json({ message: "Something was created..." });
 });
 ```
 
@@ -424,6 +472,8 @@ server.route("get", "/", (req, res, next) => {
 });
 ```
 
+The third argument (the MIME type) is optional. When omitted, Cpeak infers it from the file extension using the registry on the `cpeak()` constructor.
+
 You can then inject the variables into your file in {{ variable_name }} like this:
 
 ```HTML
@@ -463,7 +513,7 @@ server.route("get", "/dashboard", (req, res) => {
   // Signed cookies — returns false if the signature is invalid or the value was tampered with
   const userId = req.signedCookies.userId;
 
-  res.status(200).json({ theme, userId });
+  return res.status(200).json({ theme, userId });
 });
 ```
 
@@ -477,7 +527,7 @@ server.route("post", "/login", (req, res) => {
   // A signed cookie
   res.cookie("userId", "abc123", { signed: true, httpOnly: true, secure: true });
 
-  res.status(200).json({ message: "Logged in" });
+  return res.status(200).json({ message: "Logged in" });
 });
 ```
 
@@ -651,13 +701,11 @@ Here you can see all the features that Cpeak offers (excluding the authenticatio
 ```javascript
 import cpeak, { serveStatic, parseJSON, render, cookieParser, cors } from "cpeak";
 
-const server = cpeak();
+const server = cpeak({
+  mimeTypes: { mp3: "audio/mpeg" }
+});
 
-server.beforeEach(
-  serveStatic("./public", {
-    mp3: "audio/mpeg"
-  })
-);
+server.beforeEach(serveStatic("./public"));
 
 server.beforeEach(render());
 
@@ -681,11 +729,11 @@ server.beforeEach((req, res, next) => {
 });
 
 // A middleware function that can be specified to run before some particular routes
-const testRouteMiddleware = (req, res, next, handleErr) => {
+const testRouteMiddleware = (req, res, next) => {
   req.whatever = "some calculated value maybe";
 
   if (req.params.test !== "something special") {
-    return handleErr({ status: 400, message: "an error message" });
+    throw { status: 400, message: "an error message" };
   }
 
   next();
@@ -722,7 +770,7 @@ server.route("get", "/api/document/:title", testRouteMiddleware, (req, res) => {
     throw { status: 400, message: "Invalid property." };
 
   // Sending a JSON response
-  res.status(200).json({ message: "This is a test response" });
+  return res.status(200).json({ message: "This is a test response" });
 });
 
 // Reading and setting cookies
@@ -732,22 +780,22 @@ server.route("post", "/login", (req, res) => {
 
   // Set a signed session cookie
   res.cookie("sessionId", "abc123", { signed: true, httpOnly: true, secure: true });
-  res.status(200).json({ message: "Logged in" });
+  return res.status(200).json({ message: "Logged in" });
 });
 
 // Sending a file response
 server.route("get", "/file", (req, res) => {
   // Make sure to specify a correct path and MIME type...
-  res.status(200).sendFile("<path-to-file-relative-to-cwd>", "<mime-type>");
+  return res.status(200).sendFile("<path-to-file-relative-to-cwd>", "<mime-type>");
 });
 
 // Handle all the errors that could happen in the routes
 server.handleErr((error, req, res) => {
   if (error && error.status) {
-    res.status(error.status).json({ error: error.message });
+    return res.status(error.status).json({ error: error.message });
   } else {
     console.error(error);
-    res.status(500).json({
+    return res.status(500).json({
       error: "Sorry, something unexpected happened from our side."
     });
   }

package/dist/index.d.ts

@@ -1,57 +1,38 @@
-import * as net from 'net';
-import http, { IncomingMessage, ServerResponse } from 'node:http';
+import http, { IncomingMessage, ServerResponse, Server } from 'node:http';
+import net from 'node:net';
 import { Readable } from 'node:stream';
 import { Buffer } from 'node:buffer';
 import * as node_zlib from 'node:zlib';
 
-interface PbkdfOptions {
-    iterations?: number;
-    keylen?: number;
-    digest?: string;
-    saltSize?: number;
-}
-interface AuthOptions extends PbkdfOptions {
-    secret: string;
-    saveToken: (tokenId: string, userId: string, expiresAt: Date) => Promise<void>;
-    findToken: (tokenId: string) => Promise<{
-        userId: string;
-        expiresAt: Date;
-    } | null>;
-    tokenExpiry?: number;
-    hmacAlgorithm?: string;
-    tokenIdSize?: number;
-    revokeToken?: (tokenId: string) => Promise<void>;
-}
-interface CookieOptions {
-    signed?: boolean;
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: "strict" | "lax" | "none";
-    maxAge?: number;
-    expires?: Date;
-    path?: string;
-    domain?: string;
-}
-type OriginInput = string | string[] | RegExp | boolean | ((origin: string | undefined) => boolean | Promise<boolean>);
-interface CorsOptions {
-    origin?: OriginInput;
-    methods?: string | string[];
-    allowedHeaders?: string | string[];
-    exposedHeaders?: string | string[];
-    credentials?: boolean;
-    maxAge?: number;
-    preflightContinue?: boolean;
-    optionsSuccessStatus?: number;
+declare function frameworkError(message: string, skipFn: Function, code?: string, status?: number): Error & {
+    code?: string;
+    cpeak_err?: boolean;
+};
+declare enum ErrorCode {
+    MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
+    FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
+    NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
+    SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
+    INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
+    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+    WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
+    COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED",
+    DUPLICATE_ROUTE = "CPEAK_ERR_DUPLICATE_ROUTE",
+    INVALID_ROUTE = "CPEAK_ERR_INVALID_ROUTE"
 }
+
 interface CompressionOptions {
     threshold?: number;
     brotli?: node_zlib.BrotliOptions;
     gzip?: node_zlib.ZlibOptions;
     deflate?: node_zlib.ZlibOptions;
 }
+type ResolvedCompressionConfig = Required<CompressionOptions>;
 
+type CpeakHttpServer = Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
 interface CpeakOptions {
     compression?: boolean | CompressionOptions;
+    mimeTypes?: StringMap;
 }
 type StringMap = Record<string, string>;
 interface CpeakRequest<ReqBody = any, ReqQueries = any> extends IncomingMessage {
@@ -63,41 +44,72 @@ interface CpeakRequest<ReqBody = any, ReqQueries = any> extends IncomingMessage
     [key: string]: any;
 }
 interface CpeakResponse extends ServerResponse {
-    sendFile: (path: string, mime: string) => Promise<void>;
+    sendFile: (path: string, mime?: string) => Promise<void>;
     status: (code: number) => CpeakResponse;
     attachment: (filename?: string) => CpeakResponse;
     cookie: (name: string, value: string, options?: any) => CpeakResponse;
     redirect: (location: string) => void;
-    json: (data: any) => void | Promise<void>;
+    json: (data: any) => Promise<void>;
     compress: (mime: string, body: Buffer | string | Readable, size?: number) => Promise<void>;
     [key: string]: any;
 }
 type Next = (err?: any) => void;
-type HandleErr = (err: any) => void;
 type Middleware<ReqBody = any, ReqParams = any> = (req: CpeakRequest<ReqBody, ReqParams>, res: CpeakResponse, next: Next) => void;
-type RouteMiddleware<ReqBody = any, ReqParams = any> = (req: CpeakRequest<ReqBody, ReqParams>, res: CpeakResponse, next: Next, handleErr: HandleErr) => void | Promise<void>;
-type Handler<ReqBody = any, ReqParams = any> = (req: CpeakRequest<ReqBody, ReqParams>, res: CpeakResponse, handleErr: HandleErr) => void | Promise<void>;
-interface Route {
-    path: string;
-    regex: RegExp;
-    middleware: RouteMiddleware[];
-    cb: Handler;
-}
-interface RoutesMap {
-    [method: string]: Route[];
-}
+type RouteMiddleware<ReqBody = any, ReqParams = any> = (req: CpeakRequest<ReqBody, ReqParams>, res: CpeakResponse, next: Next) => void | Promise<void>;
+type Handler<ReqBody = any, ReqParams = any> = (req: CpeakRequest<ReqBody, ReqParams>, res: CpeakResponse) => void | Promise<void>;
 
 declare const parseJSON: (options?: {
     limit?: number;
 }) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
-declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap, options?: {
+declare const serveStatic: (folderPath: string, options?: {
     prefix?: string;
+    live?: boolean;
 }) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
 
 declare const render: () => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
-declare const swagger: (spec: object, prefix?: string) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
+declare const swagger: (spec: object, prefix?: string) => (req: CpeakRequest, res: CpeakResponse, next: Next) => Promise<void> | undefined;
+
+interface PbkdfOptions {
+    iterations?: number;
+    keylen?: number;
+    digest?: string;
+    saltSize?: number;
+}
+interface AuthOptions extends PbkdfOptions {
+    secret: string;
+    saveToken: (tokenId: string, userId: string, expiresAt: Date) => Promise<void>;
+    findToken: (tokenId: string) => Promise<{
+        userId: string;
+        expiresAt: Date;
+    } | null>;
+    tokenExpiry?: number;
+    hmacAlgorithm?: string;
+    tokenIdSize?: number;
+    revokeToken?: (tokenId: string) => Promise<void>;
+}
+interface CookieOptions {
+    signed?: boolean;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+}
+type OriginInput = string | string[] | RegExp | boolean | ((origin: string | undefined) => boolean | Promise<boolean>);
+interface CorsOptions {
+    origin?: OriginInput;
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+    preflightContinue?: boolean;
+    optionsSuccessStatus?: number;
+}
 
 declare function hashPassword(password: string, options?: PbkdfOptions): Promise<string>;
 declare function verifyPassword(password: string, stored: string): Promise<boolean>;
@@ -109,20 +121,6 @@ declare function cookieParser(options?: {
 
 declare const cors: (options?: CorsOptions) => (req: CpeakRequest, res: CpeakResponse, next: Next) => Promise<void>;
 
-declare function frameworkError(message: string, skipFn: Function, code?: string, status?: number): Error & {
-    code?: string;
-    cpeak_err?: boolean;
-};
-declare enum ErrorCode {
-    MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
-    FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
-    NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
-    SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
-    INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
-    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
-    WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
-    COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED"
-}
 declare class CpeakIncomingMessage extends http.IncomingMessage {
     #private;
     body: any;
@@ -130,11 +128,12 @@ declare class CpeakIncomingMessage extends http.IncomingMessage {
     get query(): StringMap;
 }
 declare class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
-    sendFile(path: string, mime: string): Promise<void>;
+    _compression?: ResolvedCompressionConfig;
+    sendFile(path: string, mime?: string): Promise<void>;
     status(code: number): this;
     attachment(filename?: string): this;
     redirect(location: string): void;
-    json(data: any): void | Promise<void>;
+    json(data: any): Promise<void>;
     compress(mime: string, body: Buffer | string | Readable, size?: number): Promise<void>;
 }
 declare class Cpeak {
@@ -143,11 +142,14 @@ declare class Cpeak {
     route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]): void;
     beforeEach(cb: Middleware): void;
     handleErr(cb: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void): void;
-    listen(port: number, cb?: () => void): http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
+    listen(port: number, cb?: () => void): CpeakHttpServer;
+    listen(port: number, host: string, cb?: () => void): CpeakHttpServer;
+    listen(options: net.ListenOptions, cb?: () => void): CpeakHttpServer;
     address(): string | net.AddressInfo | null;
-    close(cb?: (err?: Error) => void): void;
+    close(cb?: (err?: Error) => void): CpeakHttpServer;
+    get server(): CpeakHttpServer;
 }
 
 declare function cpeak(options?: CpeakOptions): Cpeak;
 
-export { type AuthOptions, type CompressionOptions, type CookieOptions, type CorsOptions, Cpeak, CpeakIncomingMessage, type CpeakOptions, type CpeakRequest, type CpeakResponse, CpeakServerResponse, ErrorCode, type HandleErr, type Handler, type Middleware, type Next, type PbkdfOptions, type RouteMiddleware, type RoutesMap, auth, cookieParser, cors, cpeak as default, frameworkError, hashPassword, parseJSON, render, serveStatic, swagger, verifyPassword };
+export { type AuthOptions, type CompressionOptions, type CookieOptions, type CorsOptions, Cpeak, type CpeakHttpServer, CpeakIncomingMessage, type CpeakOptions, type CpeakRequest, type CpeakResponse, CpeakServerResponse, ErrorCode, type Handler, type Middleware, type Next, type PbkdfOptions, type RouteMiddleware, auth, cookieParser, cors, cpeak as default, frameworkError, hashPassword, parseJSON, render, serveStatic, swagger, verifyPassword };