# @ajayos/server

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

[![npm version](https://img.shields.io/npm/v/@ajayos/server.svg)](https://www.npmjs.com/package/@ajayos/server)
[![license](https://img.shields.io/npm/l/@ajayos/server.svg)](./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.