maxserver 0.0.14 → 0.0.16

package/README.md

@@ -11,63 +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();
-const address = await server.listen({
-	port: Number(process.env.PORT || 3000),
+
+const server = await maxserver({
+	port: 3000,
+	secret: "your_secret"
 });
 
-console.log("Server running at", address);
+await server.start();
 export default server;
 ```
+<br>
 
-**maxserver(options)** forwards options to fastify(options).  
-It returns the fully configured Fastify server instance.
-
-
----
+## ⚙️ Configure
+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.
 
-## ⚙️ Configuration
-Configure the server by setting variabels in your .env file.
 
 | 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:
 
@@ -80,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.
 
@@ -93,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
 
@@ -111,89 +106,75 @@ export default async function (req, res) {
 }
 ```
 
----
+<br>
+<br>
+
 
-## 🧾 Define Schemas
-Create a sibling file ending in **`.schema.js`**. 
-The schema is offcourse a jsonschema.
-This file will be auto registered.
+## 🧾 Schemas
+Create a sibling file ending with **`.schema.js`**, so it will be auto registered.  
+For example: **hello.js** and **hello.schema.js**  
 
-Schemas:
-- validate inputs
-- generate OpenAPI docs
-- control route options for example (public/private)
+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>
-
-
-## 📚 API Docs
-
-- Open in your browser **`localhost:3000/docs`**
-- OpenAPI JSON: **`/openapi.json`**
+**`‼️ Important use export default`**
 
 <br>
 
+## Route Options
+Though we don't register routes manually, we don't set route options on the register call. If needed, route options can be set on the schema object.
+For example **schema.auth = true** to enable authentication.
+So the schema holds all configs about a root and handlers the pure logic.
 
+<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`)
@@ -203,8 +184,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
 
@@ -216,9 +208,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
 
@@ -235,5 +231,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.14",
+	"version": "0.0.16",
 	"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,29 +12,60 @@ import {
 	getHttpsOptions,
 } from "./setup.js";
 
-import { setupGetAddress } from "./getAddress.js";
+import { getAddress } from "./getAddress.js";
 
 
+export default async function maxserver(config = {}) {
 
-export default async function maxserver(options = {}) {
+	const {
 
-	const app = Fastify({
-		trustProxy: true,
-		host: "0.0.0.0",
-		https: getHttpsOptions() || undefined,
+		// maxserver options
+		port = Number(process.env.PORT || 3000),
+		secret = process.env.SECRET,
+		mongodb = process.env.MONGODB,
+		docs = process.env.DOCS !== "false",
+		cors = process.env.CORS || "*",
+		openapiInfo,
+		static: isStatic = process.env.STATIC,
+		public: isPublic = process.env.PUBLIC === "true",
 
-		// To allow writing example value fields to schemas for doucumentation 
-		ajv: { customOptions: { strictSchema: false } },
-		...options,
-	});
+		// everything else goes straight to Fastify
+		...fastifyOpts
 
-	global.createError = function (code, message) {
-		const err = new Error(message);
-		err.statusCode = code;
-		return err;
+	} = config;
+
+	const maxserverConfig = {
+		port, secret, mongodb, docs, cors,
+		static: isStatic,
+		public: isPublic
 	};
 
-	setupGetAddress(app);
+
+	let app;
+	try {
+		app = Fastify({
+			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;
+	}
+
+
+	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));
+	});
+
 	await setupCookie(app);
 	await setupHelmet(app);
 	await setupCors(app);
@@ -44,6 +75,11 @@ export default async function maxserver(options = {}) {
 	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/setup.js

@@ -12,20 +12,11 @@ import apiReference from "@scalar/fastify-api-reference";
 
 import { loadRoutes } from "./routeLoader.js";
 
-
-export async function setupCookie(app) {
-	// Use COOKIE_SECRET or fall back to JWT_SECRET so you don't need a new env var immediately
-	const secret = process.env.COOKIE_SECRET || process.env.JWT_SECRET || "change-me-in-prod";
-
-	await app.register(cookie, {
-		secret,
-		hook: "onRequest", // Crucial: Ensures cookies are parsed before your route handlers run
-		parseOptions: {}
-	});
+export async function setupRoutes(app) {
+	await loadRoutes(app);
 }
 
 
-
 export async function setupHelmet(app) {
 	await app.register(helmet, {
 		contentSecurityPolicy: false,
@@ -35,21 +26,22 @@ export async function setupHelmet(app) {
 	});
 }
 
+
+
+
 export async function setupCors(app) {
 	const isProd = process.env.NODE_ENV === "production";
-	const origin = process.env.CORS_ORIGIN || true;
+	const origin = app.maxserver.cors ?? "*";
 
-	if (isProd && !process.env.CORS_ORIGIN) 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 async function setupRoutes(app) {
-	await loadRoutes(app);
-}
-
 export function getHttpsOptions() {
 	const { TLS_KEY, TLS_CERT } = process.env;
 	if (!TLS_KEY || !TLS_CERT) return null;
@@ -67,67 +59,63 @@ export function getHttpsOptions() {
 
 
 
-
-function isAuthSkippableUrl(url) {
-	if (!url) return false;
-	if (url.startsWith("/openapi.json")) return true;
-	if (url.startsWith("/docs")) return true;
-	if (url.startsWith("/static/")) return true;
-	return false;
+export async function setupCookie(app) {
+	await app.register(cookie, {
+		secret: app.maxserver.secret || "supersecret",
+		hook: "onRequest"
+	});
 }
 
+
 export async function setupJwt(app) {
-	const secret = process.env.JWT_SECRET;
-	if (!secret) return;
 
-	// because we added own cookie setup function above
-	//await app.register(cookie);
+	await app.register(jwt, {
+		secret: app.maxserver.secret || "supersecret",
+		cookie: { cookieName: "token" }
+	});
 
-	await app.register(jwt, { secret, cookie: { cookieName: "token" } });
+	app.addHook("preHandler", async function (req) {
 
-	app.addHook("onRequest", async function (req) {
+		// Let preflight requests pass
 		if (req.method === "OPTIONS") return;
 
-		const url = req.raw?.url || req.url;
-		if (isAuthSkippableUrl(url)) return;
-		if (req.routeOptions?.config?.public) return;
+		const auth =
+			req.routeOptions?.config?.auth ??
+			req.routeOptions?.schema?.auth;
 
-		await req.jwtVerify();
+		if (!auth) return;
 
+		await req.jwtVerify();
 		const u = req.user;
 		req.userId = u?.sub || u?.userId || u?.userid || u?.id || null;
 	});
+
 }
 
-export async function setupMongo(app) {
 
-	const url = process.env.MONGODB_URI;
+export async function setupMongo(app) {
+	const url = app.maxserver.mongodb;
 	if (!url) return;
-
 	await app.register(mongodb, { url });
 
-	// ObjectId is available on app.mongo after registration
 	const { ObjectId, db } = app.mongo;
-
 	global.oid = id => new ObjectId(id ? String(id) : undefined);
 	global.db = db;
 }
 
-export async function setupStatic(app) {
-	const dir = process.env.STATIC_DIR;
-	if (!dir) return;
-
-	await app.register(fastifyStatic, {
-		root: path.resolve(dir),
-		prefix: "/static/",
-	});
-}
 
 export async function setupDocs(app) {
-	const defaultSecurity = [{ bearerAuth: [] }, { cookieAuth: [] }];
+
+	const info = app.maxserver.openapiInfo || {
+		title: "API",
+		version: "1.0.0",
+	};
 
 	await app.register(swagger, {
 		openapi: {
+			info,
+			// OpenAPI 3.x: securitySchemes must be defined globally here not per route
+			// Routes only add `security: [...]` that references these scheme names
 			components: {
 				securitySchemes: {
 					bearerAuth: { type: "http", scheme: "bearer" },
@@ -137,13 +125,29 @@ export async function setupDocs(app) {
 		},
 	});
 
-	app.get("/openapi.json", { config: { public: true } }, () => app.swagger());
 
-	await app.register(apiReference, { routePrefix: "/docs", openapi: true });
+	app.get("/openapi.json", {}, () => app.swagger());
+
+	if (app.maxserver.docs != false)
+		await app.register(apiReference, { routePrefix: "/docs", openapi: true });
 
 	app.addHook("onRoute", (route) => {
-		if (route.config?.public) return;
+		const auth = route.config?.auth ?? route.schema?.auth;
+		if (!auth) return;
 		route.schema ||= {};
-		route.schema.security = defaultSecurity;
+		route.schema.security ||= [{ bearerAuth: [] }, { cookieAuth: [] }];
 	});
-}
+}
+
+
+
+export async function setupStatic(app) {
+	const dir = app.maxserver.static;
+	if (!dir) return;
+
+	await app.register(fastifyStatic, {
+		root: path.resolve(dir),
+		prefix: "/static/",
+	});
+}
+

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;