npm package: @quicore/expressjs
Description: Provides a basic setup for an Express server with configurable options. It includes features such as cookie parsing, helmet security middleware, JSON parsing, error handling, and the ability to start both HTTP and HTTPS servers.
Author: quicore
Latest version: 0.2.0


# @quicore/expressjs

> Provides a basic setup for an Express server with configurable options.  
> Includes cookie parsing, security headers via Helmet, JSON parsing with raw body capture, error handling, and support for starting both HTTP and HTTPS servers.

---

## Features

- ✅ Plug-and-play Express server setup
- 🔒 Secure by default with [Helmet](https://helmetjs.github.io/)
- 🍪 Cookie parsing with `cookie-parser`
- 🧾 JSON parsing with raw body access
- 🧱 Optional view engine and proxy trust config
- ⚡ Start HTTP and/or HTTPS server with auto-port fallback for HTTP
- 🔧 Extendable with custom routes and middlewares
- 🧼 Centralized error handling

---

## Installation

```bash
npm install @quicore/expressjs
````

---

## Usage

```js
import { QuicoreExpressServer } from '@quicore/expressjs';

const config = {
  webserver: {
    http: { port: 3000 },
    https: {
      enabled: true,
      port: 3443,
      ssl: {
        key: './ssl/server.key',
        cert: './ssl/server.cert',
      },
    },
    express: {
      cookie: true,
      helmet: true,
      urlencodedExtended: true,
      views: {
        path: './views',
        engine: 'ejs',
      },
      proxy: {
        trust: true,
      },
    },
  },
};

const server = new QuicoreExpressServer(config);

// Optional: Add custom middleware
server.use((req, res, next) => {
  console.log(`[${req.method}] ${req.url}`);
  next();
});

// Optional: Add routes
server.setRoutes([
  {
    type: 'get',
    path: '/',
    handlers: (req, res) => res.send('Hello from Quicore Express Server!'),
  },
]);

// Start both HTTP and HTTPS servers
server.initializeCommonMiddlewares();
server.startServer();
```

---

## API

### Constructor

```ts
new QuicoreExpressServer(config?: object)
```

* `config.webserver.http.port`: Port for HTTP server (default: 3000)
* `config.webserver.https`: Configuration for HTTPS server
* `config.express`: Express middleware settings

---

### Methods

| Method                                         | Description                                                                  |
| ---------------------------------------------- | ---------------------------------------------------------------------------- |
| `initializeCommonMiddlewares()`                | Sets up JSON, URL-encoded, text, raw, cookie-parser, helmet, and view engine |
| `use(...middlewares)`                          | Adds middleware(s) to the app                                                |
| `setRoutes(routes)`                            | Sets up defined route handlers                                               |
| `startHTTP()`                                  | Starts an HTTP server with fallback if port is in use                        |
| `startHTTPS()`                                 | Starts an HTTPS server with SSL settings                                     |
| `startServer()`                                | Calls both `startHTTP()` and `startHTTPS()`, and sets the error handler      |
| `setAdditionalSupportedContents(contentTypes)` | Adds custom content types to parse as raw text                               |

---

## Error Handling

All errors are logged with context (path, IP, headers, etc.) and return a structured JSON error response:

```json
{
  "error": "server_error",
  "error_description": "Internal Server Error"
}
```

---

## License

MIT