lieko-express 0.0.2 → 0.0.4

package/README.md

@@ -1,4 +1,4 @@
-# 📘 **Lieko-express — A Modern, Minimal, REST API Framework for Node.js**
+# **Lieko-express — A Modern, Minimal, REST API Framework for Node.js**
 
 A lightweight, fast, and modern Node.js REST API framework built on top of the native `http` module. Zero external dependencies for core functionality.
 
@@ -10,6 +10,10 @@ A lightweight, fast, and modern Node.js REST API framework built on top of the n
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/lieko-express.svg)](https://www.npmjs.com/package/lieko-express)
+
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/eiwSrvt/lieko-express)
+[![Discord](https://img.shields.io/discord/1399525160050102414?color=5865F2&logo=discord&logoColor=white)](https://discord.gg/EpgPqjvd)
 
 
 
@@ -102,7 +106,7 @@ app.get('/', (req, res) => {
 app.listen(3000, () => {
   console.log('Server running on port 3000');
 });
----
+```
 
 ## 🎯 Basic Usage
 
@@ -164,9 +168,13 @@ app.delete('/posts/:id', deletePost);
 ### Features
 
 ✔ Params automatically extracted
+
 ✔ Query auto-typed
+
 ✔ Body parsed and typed
+
 ✔ Wildcards available
+
 ✔ Trailing slashes handled intelligently
 
 ---
@@ -201,7 +209,7 @@ app.group('/api', auth, (api) => {
 * You can nest indefinitely
 * Works inside routers too
 
----
+
 
 # 📦 Nested Routers
 
@@ -210,11 +218,11 @@ Routers are fully nestable:
 ```js
 const { Router } = require('lieko-express');
 
-const users = Router();
+const app = Router();
 
-users.get('/', listUsers);
-users.post('/', createUser);
-users.get('/:id', getUser);
+app.get('/', listUsers);
+app.post('/', createUser);
+app.get('/:id', getUser);
 
 app.group('/api', auth, (api) => {
   api.group('/admin', requireAdmin, (admin) => {
@@ -243,12 +251,13 @@ api.group(
   }
 );
 ```
-### ✔ Router inherits middleware from its parent groups
+✔ Router inherits middleware from its parent groups
+
+✔ Paths automatically expanded
+
+✔ Perfect for modular architecture
 
-### ✔ Paths automatically expanded
 
-### ✔ Perfect for modular architecture
----
 # 🧩 API Versioning
 
 With groups, versioning becomes trivial:
@@ -263,7 +272,6 @@ app.group('/api/v2', (v2) => {
 });
 ```
 
----
 
 ### Query Parameters
 
@@ -291,7 +299,6 @@ app.get('/search', (req, res) => {
 - `"true"` → `true` (boolean)
 - `"false"` → `false` (boolean)
 
----
 
 ## 🔧 Middlewares
 
@@ -304,7 +311,7 @@ app.use((req, res, next) => {
   next();
 });
 
-// CORS middleware
+// CORS middleware (native, but you can use app.cors())
 app.use((req, res, next) => {
   res.set('Access-Control-Allow-Origin', '*');
   res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
@@ -375,8 +382,381 @@ app.use(async (req, res, next) => {
 });
 ```
 
+# **CORS**
+
+
+Lieko-Express includes a **fully built-in, high-performance CORS engine**, with:
+
+* Global CORS (`app.cors()`)
+* Route-level CORS (`app.get("/test", { cors: {...} }, handler)`—coming soon if you want it)
+* Wildcard origins (`https://*.example.com`)
+* Multiple allowed origins
+* Strict mode (reject unknown origins)
+* Credential support
+* Private Network Access (Chrome PNA)
+* Debug logging
+* Full OPTIONS preflight support
+
+---
+
+# **Enable CORS Globally**
+
+```js
+app.cors();
+```
+
+This enables default permissive CORS:
+
+| Option                | Default                       |
+| --------------------- | ----------------------------- |
+| `origin`              | `"*"`                         |
+| `methods`             | all standard methods          |
+| `headers`             | `Content-Type, Authorization` |
+| `credentials`         | false                         |
+| `maxAge`              | 86400 (24h)                   |
+| `exposedHeaders`      | none                          |
+| `strictOrigin`        | false                         |
+| `allowPrivateNetwork` | false                         |
+
+---
+
+# **Custom Global CORS Options**
+
+```js
+app.cors({
+  origin: ["https://example.com", "https://api.example.com"],
+  methods: ["GET", "POST"],
+  headers: ["Content-Type", "Authorization", "X-Custom"],
+  credentials: true,
+  maxAge: 3600,
+  exposedHeaders: ["X-RateLimit-Remaining"],
+});
+```
+
+---
+
+# **Allow All Origins (Standard Mode)**
+
+```js
+app.cors({
+  origin: "*"
+});
+```
+
+⚠️ If you also set `credentials: true`, browsers will **reject** `*`.
+Lieko will still output `*` because that's the correct spec behavior.
+
+---
+
+# **Strict Origin Mode**
+
+Strict mode ensures the incoming `Origin` header **must match exactly** one of your allowed origins.
+
+```js
+app.cors({
+  origin: ["https://myapp.com"],
+  strictOrigin: true
+});
+```
+
+If the request comes from an unauthorized origin:
+
+```json
+HTTP 403
+{
+  "success": false,
+  "error": "Origin Forbidden",
+  "message": "Origin \"https://evil.com\" is not allowed"
+}
+```
+
+---
+
+# **Wildcard Origins**
+
+Lieko-Express supports Express-style wildcard patterns:
+
+### Allow any subdomain
+
+```js
+app.cors({
+  origin: "https://*.example.com"
+});
+```
+
+Matches:
+
+* `https://api.example.com`
+* `https://dashboard.example.com`
+
+Does not match:
+
+* `http://example.com`
+* `https://example.net`
+
+---
+
+# **Allow Private Network Access (Chrome PNA)**
+
+```js
+app.cors({
+  allowPrivateNetwork: true
+});
+```
+
+When Chrome sends:
+
+```
+Access-Control-Request-Private-Network: true
+```
+
+Lieko automatically responds:
+
+```
+Access-Control-Allow-Private-Network: true
+```
+
+# Route-Level CORS
+
+Lieko-Express allows each route to override or extend the global CORS settings using a `cors` property in the route options.
+This gives you fine-grained control over cross-origin behavior on a per-endpoint basis.
+
+Route-level CORS:
+
+* Overrides global CORS
+* Supports wildcards (`https://*.example.com`)
+* Supports strict mode
+* Sends its own preflight response
+* Automatically merges with the global configuration
+* Does **not** affect other routes
+
+---
+
+## Basic Example
+
+```js
+app.get("/public", {
+  cors: { origin: "*" }
+}, (req, res) => {
+  res.ok("Public endpoint with open CORS");
+});
+```
+
+This route allows requests from **any origin**, even if global CORS is configured differently.
+
+---
+
+## 🔒 Restrict a Sensitive Route
+
+```js
+app.post("/admin/login", {
+  cors: {
+    origin: "https://dashboard.myapp.com",
+    credentials: true,
+    strictOrigin: true
+  }
+}, (req, res) => {
+  res.ok("Login OK");
+});
+```
+
+### Result:
+
+* Only `https://dashboard.myapp.com` is allowed
+* Cookies / sessions allowed
+* Any other origin receives:
+
+```json
+{
+  "success": false,
+  "error": "Origin Forbidden",
+  "message": "Origin \"https://evil.com\" is not allowed"
+}
+```
+
+Status: **403 Forbidden**
+
+---
+
+## ✨ Wildcard Origins on a Route
+
+```js
+app.get("/api/data", {
+  cors: {
+    origin: "https://*.example.com"
+  }
+}, (req, res) => {
+  res.ok({ data: 123 });
+});
+```
+
+Matches:
+
+* `https://api.example.com`
+* `https://dashboard.example.com`
+
+---
+
+## ⚙️ Full Route-Level CORS Example
+
+```js
+app.get("/user/profile", {
+  cors: {
+    origin: [
+      "https://app.example.com",
+      "https://*.trusted.dev"
+    ],
+    methods: ["GET", "PATCH"],
+    headers: ["Content-Type", "Authorization"],
+    exposedHeaders: ["X-User-Id"],
+    credentials: true,
+    maxAge: 600,
+    strictOrigin: true,
+    allowPrivateNetwork: true,
+    debug: true
+  }
+}, (req, res) => {
+  res.ok({ profile: "OK" });
+});
+```
+
+---
+
+## 📌 How Route-Level CORS Works Internally
+
+When a request hits a route:
+
+1. If global CORS is enabled → apply it.
+2. If the route defines `cors` → merge with global config.
+3. Route CORS **overrides** global CORS.
+4. If request is `OPTIONS` (preflight) → return automatic CORS response.
+5. Otherwise → run route handler.
+
+This ensures predictable behavior.
+
 ---
 
+## 📘 Route-Level CORS Options
+
+| Option                | Type       | Description                              |                                          |
+| --------------------- | ---------- | ---------------------------------------- | ---------------------------------------- |
+| `origin`              | `string    | string[]`                                | Allowed origins (`*`, domain, wildcard). |
+| `methods`             | `string[]` | Allowed HTTP methods.                    |                                          |
+| `headers`             | `string[]` | Allowed request headers.                 |                                          |
+| `exposedHeaders`      | `string[]` | Response headers exposed to the browser. |                                          |
+| `credentials`         | `boolean`  | Allow cookies/sessions.                  |                                          |
+| `maxAge`              | `number`   | Preflight cache lifetime (seconds).      |                                          |
+| `strictOrigin`        | `boolean`  | Reject non-matching origins with 403.    |                                          |
+| `allowPrivateNetwork` | `boolean`  | Enables Chrome Private Network Access.   |                                          |
+| `debug`               | `boolean`  | Logs detailed CORS decisions.            |                                          |
+
+---
+
+## 🧩 Interaction with Global CORS
+
+| Feature            | Global | Route         |
+| ------------------ | ------ | ------------- |
+| Origin             | ✔      | ✔ (overrides) |
+| Wildcards          | ✔      | ✔             |
+| Credentials        | ✔      | ✔             |
+| Strict Origin      | ✔      | ✔             |
+| Private Network    | ✔      | ✔             |
+| Debug Logging      | ✔      | ✔             |
+| Preflight Handling | ✔      | ✔             |
+| Overrides Global   | ❌      | ✔             |
+
+
+
+
+# **Enable CORS Debug Logging**
+
+```js
+app.cors({
+  debug: true
+});
+```
+
+Console output example:
+
+```
+[CORS DEBUG]
+Request: GET /users
+Origin: https://app.example.com
+Applied CORS Policy:
+  - Access-Control-Allow-Origin: https://app.example.com
+  - Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
+  - Access-Control-Allow-Headers: Content-Type, Authorization
+  - Max-Age: 86400
+Simple request handled normally
+```
+
+---
+
+# **Preflight Handling (OPTIONS)**
+
+Lieko-Express automatically handles it:
+
+### Request:
+
+```
+OPTIONS /login
+Access-Control-Request-Method: POST
+Access-Control-Request-Headers: Content-Type
+```
+
+### Lieko Response:
+
+```
+204 No Content
+Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
+Access-Control-Allow-Headers: Content-Type, Authorization
+Access-Control-Max-Age: 86400
+```
+
+---
+
+# **Credentials Support**
+
+```js
+app.cors({
+  credentials: true,
+  origin: "https://myapp.com"
+});
+```
+
+Response contains:
+
+```
+Access-Control-Allow-Credentials: true
+```
+
+---
+
+
+# **Disable CORS**
+
+Just don’t call `app.cors()`.
+CORS stays fully disabled.
+
+---
+
+# **Default CORS Configuration**
+
+```js
+this.corsOptions = {
+  enabled: false,
+  origin: "*",
+  strictOrigin: false,
+  allowPrivateNetwork: false,
+  methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  headers: ["Content-Type", "Authorization"],
+  credentials: false,
+  maxAge: 86400,
+  exposedHeaders: [],
+  debug: false
+};
+```
+
 # 🔍 Request Object
 
 Lieko’s `req` object provides:
@@ -414,8 +794,6 @@ Lieko safely handles:
 * IPv4-mapped IPv6
 * Multiple proxies
 
----
-
 
 # 🎯 Response Object (`res`)
 
@@ -434,7 +812,6 @@ Lieko enhances Node's native response object with convenient helper methods.
 | `res.json(obj)`            | Sends JSON with correct headers.         |
 | `res.end(body)`            | Ends the response manually.              |
 
----
 
 # ✅ **High-Level Helpers**
 
@@ -447,7 +824,6 @@ Lieko enhances Node's native response object with convenient helper methods.
 | `res.noContent()`        | Sends status `204` with no body.                   |
 | `res.paginated(payload)` | Standard API pagination output.                    |
 
----
 
 # ❌ **Error Helpers**
 
@@ -466,8 +842,6 @@ Lieko enhances Node's native response object with convenient helper methods.
 > { "success": false, "error": { "code": "...", "message": "..." } }
 > ```
 
----
-
 # 🧠 **Content-Type Helpers**
 
 ### **HTML**
@@ -482,7 +856,6 @@ Lieko enhances Node's native response object with convenient helper methods.
 | -------------------------- | ------------------------------------- |
 | `res.redirect(url, code?)` | Redirects the client (default `302`). |
 
----
 
 # 📦 **Low-Level Output Controls**
 
@@ -516,16 +889,82 @@ res.paginated(items, page, limit, total);
 * String errors also supported (`res.error("Invalid user")`)
 
 ---
+# Body Parsing (JSON, URL-encoded, Multipart) — 100% Native, Zero Dependencies
+
+Lieko Express ships with a **fast, secure, and fully native body parser** — no external packages, not even `body-parser`.
 
-# 📦 Body Parsing
+As soon as you create your app, body parsing is **automatically enabled**:
 
-Lieko supports:
+```js
+const app = Lieko();   // Ready to handle JSON, form-data, files, etc.
+```
+
+### Default Limits
+
+| Content-Type                          | Default Limit | Bytes             |
+|---------------------------------------|---------------|-------------------|
+| `application/json`                   | **1mb**       | ~1,048,576 bytes  |
+| `application/x-www-form-urlencoded`   | **1mb**       | ~1,048,576 bytes  |
+| `multipart/form-data` (file uploads)  | **10mb**      | ~10,485,760 bytes |
+
+That’s already **10× more generous** than Express’s default 100kb!
+
+### Change Limits — Three Super-Simple Ways
+
+#### 1. Per content-type (most common)
+
+```js
+app.json({ limit: '100mb' });        // JSON payloads only
+app.urlencoded({ limit: '50mb' });   // Classic HTML forms
+```
 
-### ✔ JSON
+#### 2. Global limit (JSON + urlencoded at once)
 
-### ✔ URL-encoded
+```js
+app.bodyParser({ limit: '50mb' });
+// Applies 50mb to both JSON and urlencoded bodies
+```
 
-### ✔ Multipart form-data (files)
+#### 3. File upload limit (multipart/form-data)
+
+```js
+app.multipart({ limit: '500mb' });   // For very large file uploads
+```
+
+You can freely combine them:
+
+```js
+const app = Lieko();
+
+app.json({ limit: '10mb' });         // Small, fast JSON APIs
+app.urlencoded({ limit: '5mb' });
+app.multipart({ limit: '1gb' });     // Allow huge file uploads
+```
+
+### Real-world Example
+
+```js
+const Lieko = require('lieko-express');
+const app = Lieko();
+
+// Accept reasonably large JSON payloads
+app.json({ limit: '25mb' });
+
+// Accept classic forms
+app.urlencoded({ limit: '10mb' });
+
+// Allow big file uploads (photos, videos, etc.)
+app.multipart({ limit: '500mb' });
+
+app.post('/upload', (req, res) => {
+  console.log('JSON body size :', Buffer.byteLength(JSON.stringify(req.body)), 'bytes');
+  console.log('Uploaded files :', Object.keys(req.files || {}));
+
+  res.ok({ received: true, files: req.files });
+});
+
+app.listen(3000);
+```
 
 Uploads end up in:
 
@@ -549,6 +988,12 @@ Query & body fields are **auto converted**:
 "null" → null  
 ```
 
+
+**No `app.use(express.json())`, no `app.use(express.urlencoded())`, no extra dependencies** — everything works out of the box, blazing fast, and fully configurable in one line.
+
+That’s the Lieko philosophy: **less boilerplate, more power**.
+
+
 ### Response Methods
 
 ```javascript
@@ -621,8 +1066,6 @@ app.post('/upload', (req, res) => {
 });
 ```
 
----
-
 ## ✅ Validation
 
 ### Built-in Validators
@@ -740,8 +1183,6 @@ const userSchema = schema({
 });
 ```
 
----
-
 ## **Boolean Example**
 
 ```js
@@ -758,8 +1199,6 @@ Accepted:
 true, false, "true", "false", 1, 0, "1", "0"
 ```
 
----
-
 ## **Email Example**
 
 ```js
@@ -771,8 +1210,6 @@ const schema = schema({
 });
 ```
 
----
-
 ## **Username with rules**
 
 ```js
@@ -787,8 +1224,6 @@ const usernameSchema = schema({
 });
 ```
 
----
-
 ## **Password strength**
 
 ```js
@@ -806,8 +1241,6 @@ const passwordSchema = schema({
 });
 ```
 
----
-
 ## **Multiple-choice fields**
 
 ```js
@@ -818,7 +1251,6 @@ const roleSchema = schema({
 });
 ```
 
----
 
 ## **Blacklist Example**
 
@@ -830,8 +1262,6 @@ const schema = schema({
 });
 ```
 
----
-
 ## **Starts / Ends With**
 
 ```js
@@ -842,11 +1272,9 @@ const schema = schema({
 });
 ```
 
----
-
 # **Advanced Validation Examples**
 
----
+
 
 ## **Cross-field validation (matching passwords)**
 
@@ -863,7 +1291,6 @@ const registerSchema = schema({
 });
 ```
 
----
 
 ## Conditional Validation (depends on another field)
 
@@ -880,7 +1307,6 @@ const orderSchema = schema({
 });
 ```
 
----
 
 ## Dynamic rules EX: `age` required only if user is not admin
 
@@ -896,7 +1322,6 @@ const schema = schema({
 });
 ```
 
----
 
 ## **Date validation**
 
@@ -912,7 +1337,6 @@ const eventSchema = schema({
 });
 ```
 
----
 
 # **Combining many validators**
 
@@ -928,7 +1352,6 @@ const schema = schema({
 });
 ```
 
----
 
 # **Optional field + rules if provided**
 
@@ -945,7 +1368,6 @@ const schema = schema({
 If nickname is empty → no validation.
 If present → must follow rules.
 
----
 
 # **Example of validation error response**
 
@@ -1014,7 +1436,6 @@ const orderSchema = schema({
 });
 ```
 
----
 
 ## 🗂️ Routers
 
@@ -1138,8 +1559,6 @@ app.use('/api/posts', postsRouter);
 app.listen(3000);
 ```
 
----
-
 ## ⚠️ Error Handling
 
 ### Custom 404 Handler
@@ -1208,7 +1627,6 @@ res.error({ code: 'CUSTOM_ERROR', status: 418 });
 }
 ```
 
----
 
 ## 🔥 Advanced Examples
 
@@ -1551,7 +1969,6 @@ const requestLogger = (req, res, next) => {
 app.use(requestLogger);
 ```
 
----
 
 ## 🎯 Complete Application Example
 
@@ -1564,7 +1981,6 @@ See the [examples](./examples) directory for a full-featured application with:
 - Middleware examples
 - Comprehensive test suite
 
----
 
 # 📊 Performance Tips (Suite)
 
@@ -1575,7 +1991,6 @@ See the [examples](./examples) directory for a full-featured application with:
 5. **Use reverse proxy headers correctly** (`trust proxy`) when hosting behind Nginx
 6. **Disable console logs in production** or use a real logger with adjustable log levels
 
----
 
 ## Debug & Introspection Tools
 
@@ -1610,6 +2025,7 @@ DEBUG REQUEST
 → Params: {"id":"42"}
 → Query: {"page":2,"active":true}
 → Body: {}
+→ Body Size: 0 bytes
 → Files: 
 ---------------------------------------------
 ```
@@ -1682,9 +2098,9 @@ You can configure:
 ```js
 app.set('trust proxy', value);
 app.set('debug', boolean);
-app.set('x-powered-by', false);
-app.set('strictTrailingSlash', false);
-app.set('allowTrailingSlash', true);
+app.set('x-powered-by', boolean);
+app.set('strictTrailingSlash', boolean);
+app.set('allowTrailingSlash', boolean);
 ```
 
 # 🌐 Trust Proxy & IP Parsing
@@ -1720,7 +2136,6 @@ Lieko correctly handles:
 * IPv4-mapped IPv6 (`::ffff:127.0.0.1`)
 * Multi-proxy headers
 
----
 
 ## 🧩 Internals & Architecture
 
@@ -1754,8 +2169,6 @@ This allows:
 * Fast matching
 
 
----
-
 ## 🧱 Extending Lieko Express
 
 Because the framework is intentionally small, you can easily extend it.
@@ -1786,8 +2199,6 @@ const timing = (req, res, next) => {
 app.use(timing);
 ```
 
----
-
 # 🔌 Plugins
 
 A plugin is simply a function receiving `app`:
@@ -1799,16 +2210,6 @@ function myPlugin(app) {
 
 myPlugin(app);
 ```
----
-
-## 🚀 Deploying Lieko Express
-
-### Node.js (PM2)
-
-```bash
-pm2 start app.js
-```
-
 ## 📦 API Reference
 
 ### `Lieko()`
@@ -1862,7 +2263,7 @@ app.notFound((req, res) => {
 
 Register a custom 500 handler.
 
----
+
 
 ## 🔍 Known Limitations
 
@@ -1876,7 +2277,6 @@ Because Lieko Express is minimalistic:
 
 Future versions may address some of these.
 
----
 
 ## 🤝 Contributing
 
@@ -1887,7 +2287,7 @@ Contributions are welcome!
 3. Commit your changes
 4. Open a pull request
 
----
+
 
 ## 📄 License