@ajayos/server

A flexible, plugin-driven Express server wrapper with first-class TypeScript support, built-in middleware, and optional HTTPS.

✨ Overview

@ajayos/server is a thin, powerful wrapper around Express that helps you:

• Start HTTP or HTTPS servers easily
• Enable common middleware using simple config flags
• Extend behavior using a plugin system
• Use flexible constructors (port, config, callbacks)
• Keep server bootstrap code clean and readable

Designed to be:

• ✅ Simple by default
• 🔌 Plugin-driven when needed
• 🧠 TypeScript-first
• 🚀 Production-ready

📦 Installation

npm install @ajayos/server

🚀 Quick Start

import SERVER from "@ajayos/server";

const app = new SERVER(3000);

app.get("/", (_req, res) => {
  res.send("Hello World");
});

app.start();

🔧 Flexible Constructors

All of the following are valid:

new SERVER(3000);
new SERVER(3000, () => console.log("started"));
new SERVER(3000, { cors: true });

new SERVER({ port: 3000 });
new SERVER({ port: 3000 }, () => console.log("started"));

⚙️ Server Configuration

interface ServerConfig {
  port?: number;

  https?: {
    key: string | Buffer;
    cert: string | Buffer;
  };

  // Built-in middleware flags
  cors?: boolean | object;
  helmet?: boolean | object;
  bodyParser?: boolean | object;
  compression?: boolean | object;
  morgan?: boolean | string;
  rateLimit?: boolean | object;
  timeout?: boolean | object;
  static?: string;

  // Plugins
  plugins?: ServerPlugin[];

  // Lifecycle hooks
  onServerStart?: () => void;
  onServerError?: (error: any) => void;
}

🔐 HTTPS Support

import fs from "fs";
import SERVER from "@ajayos/server";

new SERVER({
  port: 8443,
  https: {
    key: fs.readFileSync("./key.pem"),
    cert: fs.readFileSync("./cert.pem"),
  },
}).start();

🔌 Plugins System (3 Ways)

You can add plugins in three different ways.

✅ 1️⃣ Via Config Flags (Simplest)

new SERVER({
  port: 3000,
  cors: true,
  helmet: true,
  bodyParser: true,
  compression: true,
  morgan: "dev",
  static: "public",
}).start();

Built-in flags are internally converted into plugins automatically.

✅ 2️⃣ Via config.plugins[]

import { cors, bodyParser, static as serveStatic } from "@ajayos/server";

new SERVER({
  port: 3000,
  plugins: [cors({ origin: "*" }), bodyParser(), serveStatic("public")],
}).start();

✅ 3️⃣ Via usePlugin() (Manual)

import { cors } from "@ajayos/server";

const app = new SERVER(3000);

app.usePlugin(cors({ origin: "*" }));

app.start();

📦 Built-in Plugins List

Available out of the box:

| Plugin | Description | | --------------- | ------------------------------- | | cors() | Cross-Origin Resource Sharing | | helmet() | Security headers | | bodyParser() | JSON + URL-encoded body parsing | | compression() | Gzip / Brotli compression | | morgan() | HTTP request logging | | rateLimit() | Request rate limiting | | timeout() | Request timeout handling | | static() | Static file serving | | jsonError() | JSON parse error handling |

All plugins are available from:

import { cors, helmet, bodyParser } from "@ajayos/server";

🧩 Plugin Usage Examples

CORS

import { cors } from "@ajayos/server";

cors({ origin: "https://example.com" });

or via config:

new SERVER({
  cors: { origin: "*" },
});

Body Parser

bodyParser({ limit: "10mb" });

Static Files

import { static as serveStatic } from "@ajayos/server";

serveStatic("public");

Rate Limiting

rateLimit({
  windowMs: 60_000,
  max: 100,
});

JSON Parse Error Handling

jsonError({ error: "Invalid JSON body" });

or with callback:

jsonError((err, req, res) => {
  res.status(400).json({
    message: err.message,
    path: req.path,
  });
});

Only JSON parse errors are handled. Other errors pass through.

🧠 Express-Compatible Routing API

app.use(middleware);

app.get("/users", handler);
app.post("/users", handler);
app.put("/users/:id", handler);
app.delete("/users/:id", handler);
app.patch("/users/:id", handler);
app.all("/health", handler);

🔔 Events & Lifecycle APIs

Server Events

app.on("error", (err) => {});
app.once("close", () => {});
app.off("error", handler);

Express App Events

app.onApp("mount", () => {});
app.onceApp("mount", () => {});
app.offApp("mount", handler);

🌐 Network Utilities

const interfaces = app.getActiveNetworkInterfaces();

Returns active IPv4 addresses (excluding localhost).

🛑 Graceful Shutdown

app.close();

🧪 TypeScript Support

• Written in TypeScript
• Ships .d.ts files
• Fully typed plugin system
• Works with ESM and CommonJS

📄 License

Apache-2.0 License — free to use, modify, and distribute.