@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

``bash
npm install @ajayos/server
`

---

🚀 Quick Start

`ts
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:

`ts
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

`ts
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

`ts
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.

---

$3

`ts
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.

---

$3

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

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

---

$3

`ts
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:

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

---

🧩 Plugin Usage Examples

$3

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

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

or via config:

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

---

$3

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

---

$3

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

serveStatic("public");
`

---

$3

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

---

$3

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

or with callback:

`ts
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

`ts
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

$3

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

$3

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

---

🌐 Network Utilities

`ts
const interfaces = app.getActiveNetworkInterfaces();
`

Returns active IPv4 addresses (excluding localhost).

---

🛑 Graceful Shutdown

`ts
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.