maxserver 0.8.2 → 0.8.4

package/.github/README.md

@@ -1,6 +1,5 @@
 # maxserver
 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
@@ -123,9 +122,6 @@ export default {
 };
 ```
 
-**‼️ Important use export default**  
-Some examples in the template folder.
-
 
 ### MODELS
 You can also auto register **models** (schemas which are shared between multiple routes).  
@@ -134,6 +130,9 @@ schema or generic model, by looking if a sibling file exist or not 😉
 
 <br>
 
+**‼️ Important use export default**  
+Some examples in the template folder.
+
 
 
 ## 📚 API Docs
@@ -145,6 +144,20 @@ And you can also easily test any route.
 
 
 
+## Global Named Exports
+
+Every named export across your JavaScript files is automatically assigned to the Node.js `global` object on startup. This makes your utility functions, constants, or services instantly accessible anywhere in the application without manual `import` statements. The system safely ignores `default` exports and lifecycle hooks, and it will immediately halt with a clear console error if it detects duplicate variable names across different files.
+
+
+
+
+
+
+
+
+
+
+
 
 
 ## 🔐 Authentication
@@ -217,10 +230,22 @@ Rule of thumb: make the message something you would want to see at 03:00 in logs
 <br>
 
 
+## Autoregister Hooks
+
+Exported functions starting with `autoregister_` automatically execute on startup and receive the Fastify `app` instance. This allows files to self-inject custom hooks, plugins, or configurations locally.
+
+### Example
+```javascript
+// In any standard .js file
+export async function autoregister_custom_auth(app) {
+	app.addHook("onRequest", async (req, reply) => {
+		// Local hook logic here
+	});
+}
+```
+
+
 
-## Note
-On loading routes - possible side effects execute.
-Means you can eg declare globals.
 
 ## About
 - Dependencies: original fastify packages + scalar/fastify-api-reference

package/index.d.ts

@@ -8,16 +8,21 @@ declare global {
 
 	var global: typeof globalThis;
 
-	/** Casts a string ID to a MongoDB ObjectId using the global helper [cite: 2026-02-15]. */
+	var ENV: NodeJS.ProcessEnv & {
+		development: boolean;
+		production: boolean;
+	};
+
+	/** Casts a string ID to a MongoDB ObjectId using the global helper. */
 	var oid: (id?: string) => import("mongodb").ObjectId;
 
-	/** Access to the global MongoDB database instance [cite: 2026-02-15]. */
+	/** Access to the global MongoDB database instance. */
 	var db: import("mongodb").Db;
 
 	/**
-	 * Creates an Error object with an attached HTTP status code [cite: 2026-02-15].
+	 * Creates an Error object with an attached HTTP status code.
 	 * Fastify catches this to return a structured JSON response.
-	 * * @param code The HTTP status code (e.g., 400, 401, 403, 404).
+	 * @param code The HTTP status code (e.g., 400, 401, 403, 404).
 	 * @param message The specific failure reason returned in the JSON body.
 	 */
 	var createError: (code: number, message: string) => Error;
@@ -31,6 +36,7 @@ declare module "fastify" {
 			secret?: string;
 			mongodb?: string;
 			static?: string;
+			errorLogger?: boolean;
 		};
 	}
 

package/package.json

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

package/src/index.js

@@ -7,56 +7,54 @@ import {
 	setupMongo,
 	setupStatic,
 	setupCookie,
+	setupErrorLogger,
 } from "./setup.js";
 
-
 import { getAddress } from "./getAddress.js";
 import { setupDocs } from "./setupDocs.js";
 import { setupRoutes } from "./setupRoutes.js";
 import { setupDevSounds } from "./devSounds.js";
 
-
 import fastifyWebsocket from "@fastify/websocket";
 
 export default async function maxserver(config = {}) {
-
-
 	const {
-
-		// 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 || "*",
-		env = process.env.NODE_ENV || "development", // should be removed, define via env only
+		env = process.env.NODE_ENV || "development",
 		routesDir = process.env.ROUTESDIR || "src",
 		scalar = {},
 		openapiInfo,
 		sounds,
 		static: isStatic = process.env.STATIC,
 		public: isPublic = process.env.PUBLIC === "true",
+		errorLogger = process.env.ERROR_LOGGER === "true",
 
-		// everything else goes straight to Fastify
 		...fastifyOpts
-
 	} = config;
 
+	globalThis.ENV = {
+		...process.env,
+		development: process.env.NODE_ENV !== "production",
+		production: process.env.NODE_ENV === "production"
+	};
+
 	const maxserverConfig = {
 		port, secret, mongodb, docs, cors, env, openapiInfo, routesDir, scalar, sounds,
 		static: isStatic,
-		public: isPublic
+		public: isPublic,
+		errorLogger
 	};
 
-	if (!secret)
-		throw new Error("secret is must have");
-
+	if (!secret) throw new Error("secret is must have");
 
 	let app;
 	try {
 		app = Fastify({
 			trustProxy: true,
-			// Required to allow adding doc fields on schema
 			ajv: { customOptions: { strictSchema: false } },
 			...fastifyOpts
 		});
@@ -65,19 +63,19 @@ export default async function maxserver(config = {}) {
 		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';
+		const host = this.maxserver.public ? "0.0.0.0" : "127.0.0.1";
 		await this.listen({ port, host });
-		console.log('🟢 ', getAddress(this));
+		console.log("🟢 ", getAddress(this));
 	});
 
 	app.register(fastifyWebsocket);
 
 	await setupDevSounds(app);
+	await setupErrorLogger(app);
 	await setupCookie(app);
 	await setupHelmet(app);
 	await setupCors(app);
@@ -87,7 +85,6 @@ 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;

package/src/setup.js

@@ -8,8 +8,6 @@ import mongodb from "@fastify/mongodb";
 import fastifyStatic from "@fastify/static";
 import helmet from "@fastify/helmet";
 
-
-
 export async function setupHelmet(app) {
 	await app.register(helmet, {
 		contentSecurityPolicy: false,
@@ -20,16 +18,12 @@ export async function setupHelmet(app) {
 	});
 }
 
-
-
 export async function setupCors(app) {
 	const isProd = app.maxserver.env === "production";
 	let origin = app.maxserver.cors ?? "*";
 
-	// Fix: Credentials + "*" = Browser Error
-	// If no origin is defined in dev, we should allow the specific requester
 	if (origin === "*" && !isProd)
-		origin = true; // Fastify-cors treats 'true' as "reflect the request origin"
+		origin = true;
 
 	if (isProd && (origin === "*" || origin === true))
 		app.log.warn("CORS: allowing all origins in production with credentials is risky");
@@ -37,12 +31,10 @@ export async function setupCors(app) {
 	await app.register(cors, {
 		origin,
 		credentials: true,
-		methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+		methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
 	});
 }
 
-
-
 export async function setupCookie(app) {
 	await app.register(cookie, {
 		secret: app.maxserver.secret,
@@ -50,9 +42,6 @@ export async function setupCookie(app) {
 	});
 }
 
-
-
-
 export async function setupMongo(app) {
 	const url = app.maxserver.mongodb;
 	if (!url) return;
@@ -63,8 +52,6 @@ export async function setupMongo(app) {
 	global.db = db;
 }
 
-
-
 export async function setupJwt(app) {
 	await app.register(jwt, {
 		secret: app.maxserver.secret,
@@ -72,25 +59,17 @@ export async function setupJwt(app) {
 	});
 
 	app.addHook("preHandler", async function (req) {
-
-		// Let preflight requests pass
 		if (req.method === "OPTIONS") return;
 
 		const auth = req.routeOptions?.config?.auth;
-
 		if (!auth) return;
 
 		await req.jwtVerify();
 		const u = req.user;
 		req.userId = u?.sub || u?.userId || u?.userid || u?.id || null;
 	});
-
 }
 
-
-
-
-
 export async function setupStatic(app) {
 	const dir = app.maxserver.static;
 	if (!dir) return;
@@ -109,5 +88,17 @@ export async function setupStatic(app) {
 	await app.register(fastifyStatic, { root: abs });
 }
 
+export async function setupErrorLogger(app) {
+	if (!app.maxserver.errorLogger) return;
 
+	app.addHook("onError", async (req, res, error) => {
+		console.log("\n‼️ ERROR ‼️");
 
+		const stackLine = error.stack.split("\n")[1];
+		const match = stackLine.match(/([^\s()]+):(\d+):\d+/);
+		const file = match?.[1].replace("file://" + process.cwd(), "");
+
+		if (file) console.log(`${file} -> line ${match[2]}`);
+		console.log(error.message);
+	});
+}

package/src/setupDocs.js

@@ -2,37 +2,6 @@ import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 
 
-/*
-const schema = {
-	summary: "OpenAPI Specification",
-	description: "Returns the full OpenAPI 3.0 specification.",
-	tags: ["Docs"],
-	response: {
-		200: {
-			type: "object",
-			additionalProperties: true,
-			required: ["openapi", "info", "paths"],
-			properties: {
-				openapi: { type: "string", example: "3.0.3" },
-				info: {
-					type: "object",
-					required: ["title", "version"],
-					properties: {
-						title: { type: "string", example: "API" },
-						version: { type: "string", example: "1.0.0" }
-					}
-				},
-				paths: { type: "object", example: {} }
-			}
-		}
-	}
-};
-*/
-
-
-
-
-
 export async function setupDocs(app) {
 
 	const info = app.maxserver.openapiInfo || {
@@ -76,7 +45,7 @@ export async function setupDocs(app) {
 				persistAuth: true,
 				showDeveloperTools: "never",
 				//"expandAllModelSections": true,
-				operationsSorter: "alpha",
+				// operationsSorter: "alpha",
 				orderSchemaPropertiesBy: "preserve",
 				metaData: {
 					title: "API Docs 👨‍💻",

package/src/setupRoutes.js

@@ -54,64 +54,77 @@ function getRoute(file) {
 	};
 }
 
-/**
- * Safe dynamic import for ESM.
- */
-async function importDefault(file) {
-	return (await import(pathToFileURL(file).href)).default;
-}
-
 export async function setupRoutes(app) {
 	const root = path.resolve(app.maxserver.routesDir || "src");
 	const files = walk(root);
 
-	// 1. Pass One: Register Global Schemas (Lonely .schema.js files)
+	// 1. Pass One: Register Named Exports Globally
+	const globals = new Map();
 	for (const file of files) {
-		// Only process if no matching handler file exists
-		if (file.endsWith(".schema.js") && !fs.existsSync(file.replace(".schema.js", ".js"))) {
-			const mod = await import(pathToFileURL(file).href);
+		if (file.endsWith(".schema.js")) continue;
 
-			// Register default export + all named exports if they have an $id
-			for (const schema of Object.values(mod))
-				if (schema?.$id) app.addSchema(schema);
+		const mod = await import(pathToFileURL(file).href);
+		for (const [key, val] of Object.entries(mod)) {
+			if (key === "default" || key.startsWith("autoregister_")) continue;
+
+			if (globals.has(key)) {
+				console.error("\n❌ Global Identifier Conflict!");
+				console.error(`The export "${key}" is defined in multiple files:`);
+				console.error(`  -> ${globals.get(key)}`);
+				console.error(`  -> ${file}\n`);
+				throw new Error(`Duplicate global identifier "${key}"`);
+			}
+
+			globals.set(key, file);
+			global[key] = val;
 		}
 	}
 
-	// 2. Pass Two: Auto-register hooks
+	// 2. Pass Two: Register Global Schemas (Lonely .schema.js files)
 	for (const file of files) {
+		const isLonely = file.endsWith(".schema.js") &&
+			!fs.existsSync(file.replace(".schema.js", ".js"));
+
+		if (!isLonely) continue;
+
+		const mod = await import(pathToFileURL(file).href);
+		for (const schema of Object.values(mod))
+			if (schema?.$id) app.addSchema(schema);
+	}
+
+	// 3. Pass Three: Auto-register hooks
+	for (const file of files) {
+		if (file.endsWith(".schema.js")) continue;
+
 		const mod = await import(pathToFileURL(file).href);
 		for (const [key, fn] of Object.entries(mod))
 			if (key.startsWith("autoregister_") && typeof fn === "function") await fn(app);
 	}
 
-	// 3. Pass Three: Register Routes
-	const seen = new Map();
+	// 4. Pass Four: Collect and Group Routes by Directory
+	const groups = new Map();
 	for (const file of files) {
 		if (file.endsWith(".schema.js")) continue;
 
 		const info = getRoute(file);
 		if (!info) continue;
 
-		const key = `${info.method} ${info.url}`;
-		if (seen.has(key)) throw new Error(`Duplicate route "${key}" detected.`);
-		seen.set(key, file);
-
-		const handler = await importDefault(file);
+		const mod = await import(pathToFileURL(file).href);
+		const handler = mod.default;
 		if (typeof handler !== "function") {
-			throw new Error(`Route "${key}" in "${file}" must export a default function.`);
+			throw new Error(`Route in "${file}" must export a default function.`);
 		}
 
 		const schemaFile = file.replace(/\.js$/, ".schema.js");
 		let raw = {};
 
 		if (fs.existsSync(schemaFile)) {
-			const loaded = await importDefault(schemaFile);
+			const loaded = (await import(pathToFileURL(schemaFile).href)).default;
 			if (loaded && typeof loaded === "object") raw = loaded;
 		}
 
-		let { auth, routeOptions = {}, ...schema } = raw;
+		let { auth, order = 999, routeOptions = {}, ...schema } = raw;
 
-		// Inject 'auth' config for the global authentication hook
 		if (auth !== undefined) {
 			routeOptions = {
 				...routeOptions,
@@ -119,6 +132,33 @@ export async function setupRoutes(app) {
 			};
 		}
 
-		app[info.method](info.url, { ...routeOptions, schema }, handler);
+		const dir = path.dirname(file);
+		if (!groups.has(dir)) groups.set(dir, []);
+
+		groups.get(dir).push({
+			method: info.method,
+			url: info.url,
+			options: { ...routeOptions, schema },
+			handler,
+			order,
+			file
+		});
+	}
+
+	// Sort routes locally within each directory
+	const routes = [];
+	for (const list of groups.values()) {
+		list.sort((a, b) => a.order - b.order);
+		routes.push(...list);
+	}
+
+	// 5. Pass Five: Register Sorted Routes
+	const seen = new Map();
+	for (const r of routes) {
+		const key = `${r.method} ${r.url}`;
+		if (seen.has(key)) throw new Error(`Duplicate route "${key}" detected.`);
+		seen.set(key, r.file);
+
+		app[r.method](r.url, r.options, r.handler);
 	}
 }

package/templates/ai/BASE

@@ -0,0 +1,2 @@
+@node
+@js

package/templates/package.json

@@ -9,20 +9,5 @@
 	},
 	"type": "module",
 	"private": "true",
-	"dependencies": {},
-	"keywords": [
-		"fastify",
-		"backend",
-		"framework",
-		"node-server",
-		"api-server",
-		"auto-routes",
-		"automatic-docs",
-		"scalar",
-		"openapi",
-		"jwt-auth",
-		"mongodb",
-		"minimalist",
-		"zero-boilerplate"
-	]
+	"dependencies": {}
 }

package/templates/src/Models/user.schema.js

@@ -0,0 +1,13 @@
+export default {
+	$id: "User",
+	summary: "User Profile",
+	description: "Internal user profile including team memberships.",
+	tags: ["User"],
+	auth: true,
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		id: { type: "string" },
+		email: { type: "string" },
+	}
+};