maxserver 0.0.15 → 0.0.17

package/README.md

@@ -11,58 +11,63 @@
 I am simplifying and improving things, that it will work for everyone plugn play.
 
 
-Ready node server setup based on **Fastify** to speedup api development.
+Ready node server setup based on **Fastify** to speed up backend development.  
+maxserver stands for **maximized simplicity** and **minimum boilerplate**.
 
 - **Auto Routes**: auto imports and registers routes and schemas
 - **Auto Docs**: auto generates docs based on schemas
-- **Preconfigures JWT auth, Cores, Helmet**
+- **Preconfigures essentials**: jwt auth, cors, helmet
 - **Auto Connect MongoDB** (optional)
 - **Dev server**
 <br><br>
 
-- Dependencies: original fastify packages + scalar/fastify-api-reference (doc generator)
-- The source is simple and short. Everyone shall be able to read, understand and modify if needed.
-
 
 ## Install
 
 ### Setup ready project
+```js
 npx maxserver [appname]
+```
 
-### Install 
+### Or install as packge
+```js
 npm install maxserver
+```
+<br>
 
 ## Setup
 ```js
 import maxserver from "maxserver";
 
-const server = await maxserver();
-await server.listen();
+const server = await maxserver({
+	port: 3000,
+	secret: "your_secret"
+});
 
-console.log("Server running at ", server.getAddress());
+await server.start();
 export default server;
-
 ```
----
+<br>
 
 ## ⚙️ Configure
-Quick configure your server by passing options to the **maxserver()** or define them in your .env file.  
-You can also pass any fastify options.
+Configs can be passed to the init call to **maxserver()** or set in your .env file.  
+If you define options in env, use all upper case letters.
+Any fastify options can be passed to maxserver() too.
+
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `PORT` | `3000` | Server port |
-| `JWT_SECRET` | *-* | Enables JWT auth (private-by-default routes) |
-| `MONGODB_URI` | *-* | Enables MongoDB auto-connect + global `db` |
-| `DOCS` | `true` | Set `false` to disable docs UI at `/docs` |
-| `STATIC_DIR` | *(optional)* | Serve static files (example: `./public`) |
-| `CORS_ORIGIN` | `*` | Allowed CORS origins |
-
----
-
-## 🗂️ Project Structure
+| `port` | `3000` | Server port |
+| `secret` | *-* | Secret used for jwt and cookies |
+| `cors` | `*` | Allowed CORS origins, default all allowed |
+| `docs` | `true` | Set `false` to disable auto generated docs` |
+| `mongodb` | *-* | MongoDB URI, if set auto-connects db |
+| `public` | `false` | Set `true` to expose the server publicly (binds to `0.0.0.0`) |
+| `static` | *-* | If set, serves this directory statically |
+<br><br>
 
-**1 route = 1 handler file + 1 schema file**
+## 🗂️ Project Structure 
+Our golden rule: **1 route = 1 handler file + 1 schema file**
 
 Example:
 
@@ -75,12 +80,11 @@ src/
 		hello.schema.js
 	...
 ```
-
----
+<br>
 
 ## 🛣️ Handlers
 
-### 1) Define method + path
+#### 1) Define method + path
 Start each route file with a comment to define the path.  
 That comment is what the route loader uses to auto-register the route.
 
@@ -88,13 +92,9 @@ That comment is what the route loader uses to auto-register the route.
 // GET /teams/:id
 ```
 
+#### 2) Export default handler
 
 
-### 2) Default export handler
-
-
-### Example
-
 ```js
 // GET /teams/:id
 
@@ -106,89 +106,90 @@ export default async function (req, res) {
 }
 ```
 
----
+If you don't want to autoregister some routes, then simply don't add that magic comment 😃
 
-## 🧾 Define Schemas
-Create a sibling file ending in **`.schema.js`**. 
-The schema is offcourse a jsonschema.
-This file will be auto registered.
 
-Schemas:
-- validate inputs
-- generate OpenAPI docs
-- control route options for example (public/private)
+<br>
+<br>
+
+
+## 🧾 Schemas
+Create a sibling file ending with **`.schema.js`**, so it will be auto registered.  
+For example: **hello.js** and **hello.schema.js**  
+
+Besides the basic validation fields we can set fields like summary and description,
+which will appear in the docs. Mostly you don't need to write schemas yourself, chat gpt and gemini do it excelently.
 
 
-**`Important - use default export`**
 ```js
 export default {
-	tags: ["Teams"],
-	summary: "Get team",
-	description: "Returns a single team by identifier.",
 
-	params: {
+	tags: ["Test"],
+	summary: "Post hello",
+	description: "Accepts a name and returns a greeting.",
+
+	body: {
 		type: "object",
-		required: ["id"],
+		required: ["name"],
 		properties: {
-			id: {
+			name: {
 				type: "string",
-				minLength: 24,
-				example: "",
 			},
 		},
 	},
 
-	response: {
-		200: {
-			type: "object",
-			properties: {
-				id: {
-					type: "string",
-					example: "507f1f77bcf86cd799439011",
-				},
-				name: { type: "string", example: "Team A" },
-			},
-			required: ["id", "name"],
-		},
-	},
+	...
 };
 ```
 
-<br>
+**`‼️ Important use export default`**
 
+<br>
 
-## 📚 API Docs
+## 🛠️ Route Options
+Though we don't mostly register routes manually, we don't set route options on the register call.  
+If needed, you can wether register that route manually or just set them on the schema.
 
-- Open in your browser **`localhost:3000/docs`**
-- OpenAPI JSON: **`/openapi.json`**
+```js
+// Inside schema
 
-<br>
+export default {
+	routeOptions: {
+		config: {
+			preHandler: ...
+		},
+	},
+	...
+```
 
 
+<br>
 
+## 📚 API Docs
 
-## 🔐 Authentication (JWT)
+Open in your browser **`localhost:3000/docs`**  
+OpenAPI JSON: **`/openapi.json`**
 
-Enable auth by setting:
+<br>
 
-- `JWT_SECRET`
 
-Behavior:
-- **Private by default**: routes require JWT (cookie or Bearer header)
-- Authenticated user identifier is available as **`req.userId`**
-- Make a route **public** by setting `config.public: true` in its schema
+## 🔐 Authentication
+JWT header and cookie based auth is preconfigured.  
+To enable auth for a route set in it's schema **auth = true**  
+The authenticated user is available as **`req.userId`**
 
 ```js
+// Inside schema
+
 export default {
-	config: { public: true },
-	// ...
+	auth: true
 };
 ```
 
 <br>
 
 ## 🍃 MongoDB
-Define in the env **`MONGODB_URI`** and it will auto-connect at server start and you get:
+Set option **`MONGODB`** your mongodbURI and it will auto-connect at server start and you get:
 
 - global **`db`** (connected database handle)
 - global **`oid(string)`** (string → MongoDB `ObjectId`)
@@ -198,8 +199,19 @@ Define in the env **`MONGODB_URI`** and it will auto-connect at server start and
 | `db` | MongoDB database handle | Use it directly in handlers |
 | `oid(id)` | string → `ObjectId` | Avoid importing `ObjectId` everywhere |
 
+### Example
 
----
+```js
+// Inside route handlers
+
+export default async function (req, res) {
+
+	await db.feedback.insert(...)
+}
+```
+
+
+<br>
 
 ## 🧰 Error Handling
 
@@ -211,9 +223,13 @@ if (!user) throw createError(404, "User not found");
 
 Rule of thumb: make the message something you would want to see at 03:00 in logs.
 
----
+<br>
 
+## About
+- Dependencies: original fastify packages + scalar/fastify-api-reference
+- The source is simple. Everyone can read, understand and modify if needed.
 
+<br>
 
 ## 🛠️ Tips & Tools
 
@@ -230,5 +246,6 @@ In `.vscode/tasks.json`, enable the task with:
 "runOptions": { "runOn": "folderOpen" }
 ```
 
-### 🤖 AI Assistants (Code Style)
-Copy **`RULES.md`** into your AI tool as system context, then ask it to generate routes + schemas.
+### 🤖 AI Assistants
+Copy **`RULES.md`** into your AI tool as system context,  
+then ask it to generate routes + schemas.

package/bin/init.js

@@ -15,17 +15,17 @@ function main() {
 	}
 
 	try {
-		console.log(`🚀 Creating "${projectName}"...`);
+		console.log(`🚀 Setting up "${projectName}"...`);
 		fs.cpSync(templateDir, targetDir, { recursive: true });
 
 		fixDotfiles(targetDir);
 		patchPackageJson(targetDir, projectName);
 
 		process.chdir(targetDir);
-		console.log("📦 Installing maxserver...");
+		console.log("📦 Installing maxserver");
 		execSync("npm install maxserver@latest", { stdio: "inherit" });
 
-		console.log("\n✅ Done! Your project is ready. 😊");
+		console.log(`\n✅ Install complete\n\ncd ${projectName}\nnpm run dev\n`);
 	} catch (err) {
 		console.error("❌ Init failed:", err.message);
 		process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "maxserver",
-	"version": "0.0.15",
+	"version": "0.0.17",
 	"description": "Node server setup based fastify",
 	"author": "Max Matinpalo",
 	"type": "module",

package/src/getAddress.js

@@ -1,29 +1,5 @@
 import os from "node:os";
 
-export function setupGetAddress(app) {
-	app.decorate("getAddress", () => {
-		const addr = app.server?.address();
-		const protocol = app.initialConfig?.https ? "https" : "http";
-
-		if (!addr) return null;
-		if (typeof addr === "string") return addr;
-
-		const isPublicBind = addr.address === "0.0.0.0" || addr.address === "::";
-		const isLoopback = addr.address === "127.0.0.1" || addr.address === "::1";
-
-		const envIp = String(process.env.PUBLIC_IP || "").trim() || null;
-		const detectedIp = envIp || getLanIp();
-
-		const ip = (isPublicBind && !isLoopback)
-			? (detectedIp || addr.address)
-			: "localhost";
-
-		const host = ip.includes(":") ? `[${ip}]` : ip;
-
-		return `${protocol}://${host}:${addr.port}`;
-	});
-}
-
 function getLanIp() {
 	const nets = os.networkInterfaces();
 
@@ -35,3 +11,28 @@ function getLanIp() {
 
 	return null;
 }
+
+
+export function getAddress(app) {
+
+	const addr = app.server?.address();
+	const protocol = app.initialConfig?.https ? "https" : "http";
+
+	if (!addr) return null;
+	if (typeof addr === "string") return addr;
+
+	const isPublicBind = addr.address === "0.0.0.0" || addr.address === "::";
+	const isLoopback = addr.address === "127.0.0.1" || addr.address === "::1";
+
+	const envIp = String(process.env.PUBLIC_IP || "").trim() || null;
+	const detectedIp = envIp || getLanIp();
+
+	const ip = (isPublicBind && !isLoopback)
+		? (detectedIp || addr.address)
+		: "localhost";
+
+	const host = ip.includes(":") ? `[${ip}]` : ip;
+
+	return `${protocol}://${host}:${addr.port}`;
+}
+

package/src/index.js

@@ -12,7 +12,7 @@ import {
 	getHttpsOptions,
 } from "./setup.js";
 
-import { setupGetAddress } from "./getAddress.js";
+import { getAddress } from "./getAddress.js";
 
 
 export default async function maxserver(config = {}) {
@@ -20,47 +20,53 @@ export default async function maxserver(config = {}) {
 	const {
 
 		// maxserver options
+		port = Number(process.env.PORT || 3000),
 		secret = process.env.SECRET,
-		cookieSecret = process.env.COOKIE_SECRET,
-		mongodbUri = process.env.MONGODB_URI,
+		mongodb = process.env.MONGODB,
 		docs = process.env.DOCS !== "false",
-		staticDir = process.env.STATIC_DIR,
-		corsOrigin = process.env.CORS_ORIGIN || "*",
+		cors = process.env.CORS || "*",
+		env = process.env.NODE_ENV || "development",
+		openapiInfo,
+		static: isStatic = process.env.STATIC,
+		public: isPublic = process.env.PUBLIC === "true",
 
 		// everything else goes straight to Fastify
 		...fastifyOpts
 
 	} = config;
 
-	if (process.env.NODE_ENV == "development") {
-		console.error("Please define secret in env !");
-
-	}
-
-	let maxserverConfig = {
-		secret, mongodbUri, docs, staticDir, corsOrigin
+	const maxserverConfig = {
+		port, secret, mongodb, docs, cors,
+		static: isStatic,
+		public: isPublic
 	};
 
-	process.env.NODE_ENV;
-
-
-
 
-	const app = Fastify({
+	let app;
+	try {
+		app = Fastify({
+			https: getHttpsOptions() || undefined,
+			trustProxy: true,
 
-		https: getHttpsOptions() || undefined,
-		trustProxy: true,
+			// Required to allow adding doc fields on schema
+			ajv: { customOptions: { strictSchema: false } },
+			...fastifyOpts
+		});
+	} catch (err) {
+		console.error("❌ Fastify initialization failed:", err);
+		throw err;
+	}
 
-		// To allow writing example value fields to schemas for doucumentation 
-		ajv: { customOptions: { strictSchema: false } },
-		...fastifyOpts,
-	});
 
 	app.decorate("maxserver", maxserverConfig);
 
+	app.decorate("start", async function () {
+		const port = this.maxserver.port ?? 3000;
+		const host = this.maxserver.public ? '0.0.0.0' : '127.0.0.1';
+		await this.listen({ port, host });
+		console.log('Server running at ', getAddress(this));
+	});
 
-
-	setupGetAddress(app);
 	await setupCookie(app);
 	await setupHelmet(app);
 	await setupCors(app);
@@ -70,13 +76,11 @@ export default async function maxserver(config = {}) {
 	await setupDocs(app);
 	await setupRoutes(app);
 
-
 	global.createError = function (code, message) {
 		const err = new Error(message);
 		err.statusCode = code;
 		return err;
 	};
 
-
 	return app;
 }

package/src/routeLoader.js

@@ -1,89 +1,91 @@
-// Scans src/** for files whose first line looks like:
-// POST /teams/create
-// Imports handler + schema and registers them with Fastify.
+/**
+ * 🚀 AUTO-LOADER
+ * Scans src/ for files with "// METHOD /url" comments.
+ * Automatically registers them as Fastify routes.
+ */
 
 import fs from "fs";
 import path from "path";
+import { pathToFileURL } from "url";
 
-const ROUTE_OPTION_KEYS = new Set([
-	"config",
-	"preHandler",
-	"onRequest",
-	"preValidation",
-	"preSerialization",
-	"errorHandler",
-	"logLevel",
-	"bodyLimit",
-	"attachValidation",
-	"exposeHeadRoute",
-	"constraints",
-	"timeout",
-	"websocket",
-	"prefixTrailingSlash",
-]);
 
+// Matches lines like: // GET /api/v1/users
+const ROUTE_REGEX = /^\/\/\s*(GET|POST|PUT|PATCH|DELETE)\s+(.+)$/gm;
+
+
+/**
+ * Recursively finds all .js files in a directory.
+ * Skips node_modules and dotfiles.
+ */
 function walk(dir, out = []) {
 	if (!fs.existsSync(dir)) return out;
-	const entries = fs.readdirSync(dir, { withFileTypes: true });
 
-	for (const entry of entries) {
-		if (entry.name === "node_modules") continue;
-		if (entry.name.startsWith(".")) continue;
-		const full = path.join(dir, entry.name);
+	for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (e.name === "node_modules") continue;
+		if (e.name.startsWith(".")) continue;
 
-		if (entry.isDirectory()) {
+		const full = path.join(dir, e.name);
+		if (e.isDirectory()) {
 			walk(full, out);
-		} else if (entry.name.endsWith(".js")) {
-			out.push(full);
+			continue;
 		}
+
+		if (!e.name.endsWith(".js")) continue;
+		out.push(full);
 	}
+
 	return out;
 }
 
-function getFirstLine(file) {
+
+/**
+ * Extracts method and URL from the file's "magic comment".
+ * Enforces strict "One Route Per File" policy.
+ */
+function getRoute(file) {
 	const text = fs.readFileSync(file, "utf8");
-	const lines = text.split("\n");
-	const firstContent = lines.find((line) => line.trim().length > 0);
+	const matches = [...text.matchAll(ROUTE_REGEX)];
 
-	return (firstContent || "").trim().replace(/^\uFEFF/, "");
-}
+	if (matches.length === 0) return null;
 
-const ROUTE_REGEX = /^\/\/\s*(GET|POST|PUT|PATCH|DELETE)\s+(.+)$/;
+	// Warn if user accidentally defines multiple routes in one file
+	if (matches.length > 1) {
+		console.warn(
+			`⚠️ Ignored "${file}": Found ${matches.length} route comments. ` +
+			`Only 1 allowed per file.`
+		);
+		return null;
+	}
 
-function parseRouteComment(file) {
-	const line = getFirstLine(file);
-	const m = line.match(ROUTE_REGEX);
-	if (!m) return null;
+	const m = matches[0];
+	const method = m[1].toLowerCase();
+	// Normalize URL: Remove all leading slashes, then add exactly one
+	const url = "/" + m[2].trim().replace(/^\/+/, "");
 
-	return { method: m[1].toLowerCase(), url: m[2] };
+	return { method, url };
 }
 
-function splitSchemaExport(raw) {
-	const routeOptions = {};
-	const schema = {};
-
-	for (const [key, value] of Object.entries(raw || {})) {
-		if (ROUTE_OPTION_KEYS.has(key)) {
-			routeOptions[key] = value;
-			continue;
-		}
-		schema[key] = value;
-	}
 
-	return { routeOptions, schema };
+/**
+ * Safe dynamic import that handles Windows paths correctly.
+ */
+async function importDefault(file) {
+	return (await import(pathToFileURL(file).href)).default;
 }
 
+
 export async function loadRoutes(fastify) {
-	const ROOT = path.join(process.cwd(), "src");
-	const files = walk(ROOT);
 	const seen = new Map();
+	const root = path.join(process.cwd(), "src");
 
-	for (const file of files) {
+	for (const file of walk(root)) {
+		// Skip schema files; they are loaded alongside their route file
 		if (file.endsWith(".schema.js")) continue;
 
-		const info = parseRouteComment(file);
+		const info = getRoute(file);
 		if (!info) continue;
 
+		// 🛡️ Collision Detection: Ensure no two files claim the same route
 		const key = info.method + " " + info.url;
 		if (seen.has(key)) {
 			throw new Error(
@@ -94,29 +96,35 @@ export async function loadRoutes(fastify) {
 		}
 		seen.set(key, file);
 
-		const handlerMod = await import("file://" + file);
-		const handler = handlerMod.default;
+		// Import the route handler
+		const handler = await importDefault(file);
+		if (typeof handler !== "function") {
+			throw new Error(
+				`Route "${key}" in "${file}" must export a default function.`
+			);
+		}
 
+		// 🤝 Schema Loading: Look for sibling .schema.js file
 		const schemaFile = file.replace(/\.js$/, ".schema.js");
-		let raw = null;
+		let raw = {};
 
 		if (fs.existsSync(schemaFile)) {
-			const schemaMod = await import("file://" + schemaFile);
-			raw = schemaMod.default || {};
-		} else {
-			fastify.log.warn(
-				`Route schema missing: ` +
-				`${info.method.toUpperCase()} ${info.url}`
-			);
-			raw = {};
+			const loaded = await importDefault(schemaFile);
+			// 🛡️ Guard: Ensure export is a valid object before using it
+			if (loaded && typeof loaded === "object") raw = loaded;
 		}
 
-		const parts = splitSchemaExport(raw);
+		// ✨ Magic: Extract 'auth' and 'routeOptions' specifically
+		let { auth, routeOptions = {}, ...schema } = raw;
 
-		fastify[info.method](
-			info.url,
-			{ ...parts.routeOptions, schema: parts.schema },
-			handler
-		);
+		// Inject 'auth' into config if present (Syntactic Sugar)
+		if (auth !== undefined) {
+			routeOptions = {
+				...routeOptions,
+				config: { ...(routeOptions.config || {}), auth: !!auth },
+			};
+		}
+
+		fastify[info.method](info.url, { ...routeOptions, schema }, handler);
 	}
-}
+}

package/src/setup.js

@@ -27,18 +27,21 @@ export async function setupHelmet(app) {
 }
 
 
+
+
 export async function setupCors(app) {
 	const isProd = process.env.NODE_ENV === "production";
-	const origin = app.maxserver.corsOrigin ?? true;
+	const origin = app.maxserver.cors ?? "*";
 
-	if (isProd && origin === true) {
-		app.log.warn("CORS origin not set, allowing all origins");
+	if (isProd && origin === "*") {
+		app.log.warn("CORS: allowing all origins (*) in production");
 	}
 
 	await app.register(cors, { origin });
 }
 
 
+
 export function getHttpsOptions() {
 	const { TLS_KEY, TLS_CERT } = process.env;
 	if (!TLS_KEY || !TLS_CERT) return null;
@@ -91,7 +94,7 @@ export async function setupJwt(app) {
 
 
 export async function setupMongo(app) {
-	const url = app.maxserver.mongodbUri;
+	const url = app.maxserver.mongodb;
 	if (!url) return;
 	await app.register(mongodb, { url });
 
@@ -139,7 +142,7 @@ export async function setupDocs(app) {
 
 
 export async function setupStatic(app) {
-	const dir = app.maxserver.staticDir;
+	const dir = app.maxserver.static;
 	if (!dir) return;
 
 	await app.register(fastifyStatic, {

package/templates/env

@@ -1,24 +1,8 @@
-# Environment
-NODE_ENV = development
-
-# Server
-PORT = 3000
-
-# CORS(prod only, ignored in dev)
-# CORS_ORIGIN = https://app.example.com
-
-# JWT;
-# JWT_SECRET = supersecretkey
 
-# MongoDB;
-# MONGODB_URI = mongodb://127.0.0.1:27017/testdb
-
-# Static files
-# STATIC_DIR =./ public
-
-# API Docs in production
-DOCS = 1
+NODE_ENV = development
 
-# Optional HTTPS(direct TLS, no nginx)
-# TLS_KEY = /etc/ssl / private / server.key
-# TLS_CERT = /etc/ssl / certs / server.crt;
+# PORT
+# CORS
+# SECRET
+# MONGODB
+# STATIC 

package/templates/server.js

@@ -1,10 +1,9 @@
 import maxserver from "maxserver";
 
-const server = await maxserver();
-
-await server.listen({
-	port: Number(process.env.PORT || 3000),
+const server = await maxserver({
+	port: 3000,
+	secret: "your_secret"
 });
 
-console.log("Server running at ", server.getAddress());
+await server.start();
 export default server;