@ajayos/server
Version:
A lightweight Express-based HTTP/HTTPS server wrapper with built-in middleware, lifecycle hooks, logging, and utility helpers.
327 lines (224 loc) • 5.41 kB
Markdown
# @ajayos/server
> A flexible, plugin-driven Express server wrapper with first-class TypeScript support, built-in middleware, and optional HTTPS.
[](https://www.npmjs.com/package/@ajayos/server)
[](./LICENSE)
## ✨ 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**.
### ✅ 1️⃣ Via Config Flags (Simplest)
```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.
### ✅ 2️⃣ Via `config.plugins[]`
```ts
import { cors, bodyParser, static as serveStatic } from "@ajayos/server";
new SERVER({
port: 3000,
plugins: [cors({ origin: "*" }), bodyParser(), serveStatic("public")],
}).start();
```
### ✅ 3️⃣ Via `usePlugin()` (Manual)
```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
### CORS
```ts
import { cors } from "@ajayos/server";
cors({ origin: "https://example.com" });
```
or via config:
```ts
new SERVER({
cors: { origin: "*" },
});
```
### Body Parser
```ts
bodyParser({ limit: "10mb" });
```
### Static Files
```ts
import { static as serveStatic } from "@ajayos/server";
serveStatic("public");
```
### Rate Limiting
```ts
rateLimit({
windowMs: 60_000,
max: 100,
});
```
### JSON Parse Error Handling
```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
### Server Events
```ts
app.on("error", (err) => {});
app.once("close", () => {});
app.off("error", handler);
```
### Express App Events
```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.