maxserver 0.8.3 → 1.0.1

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.3",
+	"version": "1.0.1",
 	"description": "Node server setup based fastify",
 	"author": "Max Matinpalo",
 	"type": "module",

package/src/devSounds.js

@@ -1,31 +1,29 @@
-// Development sounds  to make api development even more fun 😃
+// Development sounds to make api development even more fun 😃
 
-
-import { exec } from 'child_process';
+import { exec } from "child_process";
 
 export async function setupDevSounds(app) {
 	if (!app.maxserver.sounds) return;
-	if (app.maxserver.env === 'production' || process.env.CI) return;
-
-	// Using here some builtin macos sounds see file paths
-	// For windows we should add alternative
-	if (process.platform !== 'darwin') return;
-	const ok = '/System/Library/Sounds/Glass.aiff';
-	const err = '/System/Library/Sounds/Submarine.aiff';
-
-
+	if (app.maxserver.env !== "development" || process.env.CI) return;
+	if (process.platform !== "darwin") return;
 
+	const ok = "/System/Library/Sounds/Glass.aiff";
+	const err = "/System/Library/Sounds/Submarine.aiff";
 
-	const play = file => exec(`afplay "${file}" >/dev/null 2>&1 &`);
+	let lastPlayed = 0;
 
-	app.addHook('onResponse', async (req, reply) => {
+	const play = file => {
+		const now = Date.now();
+		if (now - lastPlayed < 1000) return;
+		lastPlayed = now;
+		exec(`afplay "${file}" >/dev/null 2>&1 &`);
+	};
 
-		// Dev sounds only for api requests - not for static served files 😃
-		const ct = String(reply.getHeader('content-type') || '').toLowerCase();
+	app.addHook("onResponse", async (req, reply) => {
+		const ct = String(reply.getHeader("content-type") || "").toLowerCase();
 		const disabled = req.routeOptions?.config?.devSound === false;
-		let trigger = ct && ct.includes('application/json') && !disabled;
+		const trigger = ct && ct.includes("application/json") && !disabled;
 
-		// Though this is route is auto registered by scalar, and we can't set sounds false on it...
 		if (req.url === "/docs/openapi.json") return;
 
 		if (trigger) {
@@ -34,4 +32,4 @@ export async function setupDevSounds(app) {
 			else play(err);
 		}
 	});
-}
+}

package/src/index.js

@@ -7,56 +7,52 @@ 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,
+		sounds = true,
 		static: isStatic = process.env.STATIC,
 		public: isPublic = process.env.PUBLIC === "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
 	};
 
-	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 +61,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 +83,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.env !== "development") return;
 
+	app.addHook("onError", async (req, res, error) => {
+		console.log("\n\x1b[1;31mERROR\x1b[0m");
 
+		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

@@ -48,7 +48,7 @@ export async function setupDocs(app) {
 				// operationsSorter: "alpha",
 				orderSchemaPropertiesBy: "preserve",
 				metaData: {
-					title: "API Docs 👨‍💻",
+					title: "Server",
 				},
 				authentication: {
 					preferredSecurityScheme: 'bearerAuth',

package/templates/jsconfig.json

@@ -4,19 +4,11 @@
 		"module": "ES2020",
 		"target": "ES2020",
 		"moduleResolution": "bundler",
-		"jsx": "react-jsx",
 		"strict": false,
 		"noUnusedParameters": false,
 		"noUnusedLocals": false,
 		"noImplicitAny": false,
-		// new attempt to reduce noise
 		"skipLibCheck": true,
-		//"baseUrl": ".",
-		"paths": {
-			"*": [
-				"./src/*"
-			],
-		},
 		"types": [
 			"node",
 			"maxserver"

package/templates/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "__NAME__",
-	"version": "1.0.0",
+	"version": "0.1.0",
 	"description": "",
 	"main": "server.js",
 	"scripts": {

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" },
+	}
+};

package/templates/src/ai/BASE

@@ -0,0 +1,4 @@
+@node
+@js
+@outjson
+../

package/templates/ai/BASE

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