maxserver 0.1.6 → 0.1.8

package/README.md

@@ -229,11 +229,8 @@ Rule of thumb: make the message something you would want to see at 03:00 in logs
 ## 🛠️ Tips & Tools
 
 ### 🔌 Scalar API Client (Live Testing)
-- Download the great new api client
-- It autosyncs well with the server
-- Add Item → Import from OpenAPI
-- Paste: `http://localhost:3000/openapi.json`
-- Enable watch mode for live updates
+- Open: `http://localhost:3000/docs`
+
 
 ### ⚡ VS Code Auto-Start
 In `.vscode/tasks.json`, enable the task with:

package/package.json

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

package/src/index.js

@@ -6,12 +6,12 @@ import {
 	setupJwt,
 	setupMongo,
 	setupStatic,
-	setupDocs,
 	setupCookie,
 } from "./setup.js";
 
 
 import { getAddress } from "./getAddress.js";
+import { setupDocs } from "./setupDocs.js";
 import { setupRoutes } from "./setupRoutes.js";
 
 

package/src/setup.js

@@ -7,8 +7,7 @@ import cookie from "@fastify/cookie";
 import mongodb from "@fastify/mongodb";
 import fastifyStatic from "@fastify/static";
 import helmet from "@fastify/helmet";
-import swagger from "@fastify/swagger";
-import apiReference from "@scalar/fastify-api-reference";
+
 
 
 export async function setupHelmet(app) {
@@ -78,42 +77,6 @@ export async function setupJwt(app) {
 
 
 
-export async function setupDocs(app) {
-
-	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" },
-					cookieAuth: { type: "apiKey", in: "cookie", name: "token" },
-				},
-			},
-		},
-	});
-
-
-	app.get("/openapi.json", {}, () => app.swagger());
-
-	if (app.maxserver.docs !== false)
-		await app.register(apiReference, { routePrefix: "/docs", openapi: true });
-
-	app.addHook("onRoute", (route) => {
-		const auth = route.config?.auth;
-		if (!auth) return;
-		route.schema ||= {};
-		route.schema.security ||= [{ bearerAuth: [] }, { cookieAuth: [] }];
-	});
-}
-
-
 
 export async function setupStatic(app) {
 	const dir = app.maxserver.static;

package/src/setupDocs.js

@@ -0,0 +1,78 @@
+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 for this API in JSON format.",
+	tags: ["Docs"],
+	response: {
+		200: {
+			type: "object",
+			additionalProperties: true,
+			properties: {
+				openapi: {
+					type: "string",
+					example: "3.0.3"
+				},
+				info: {
+					type: "object",
+					properties: {
+						title: { type: "string", example: "maxserver API" },
+						version: { type: "string", example: "1.0.0" }
+					},
+					required: ["title", "version"]
+				},
+				paths: {
+					type: "object",
+					example: {}
+				}
+			},
+			required: ["openapi", "info", "paths"]
+		}
+	}
+};
+
+
+
+
+
+export async function setupDocs(app) {
+
+	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" },
+					cookieAuth: { type: "apiKey", in: "cookie", name: "token" },
+				},
+			},
+		},
+	});
+
+
+	app.get("/openapi.json", { schema }, () => app.swagger());
+
+	if (app.maxserver.docs !== false)
+		await app.register(apiReference, { routePrefix: "/docs", openapi: true });
+
+	app.addHook("onRoute", (route) => {
+		const auth = route.config?.auth;
+		if (!auth) return;
+		route.schema ||= {};
+		route.schema.security ||= [{ bearerAuth: [] }, { cookieAuth: [] }];
+	});
+}
+
+
+
+

package/templates/src/Tests/hello.js

@@ -0,0 +1,14 @@
+// POST /hello
+
+export default async function handler(req, rep) {
+
+	console.log("POST /hello");
+
+	return {
+		message: `Hello ${req.body.name} again 🙋‍♂️`,
+	};
+}
+
+
+
+// Try POST with and without name, to see how the schema works

package/templates/src/Tests/hello.schema.js

@@ -0,0 +1,27 @@
+export default {
+	summary: "Test post hello",
+	description: "Receives a name in the body and returns a personalized hello message.",
+	tags: ["Tests"],
+	body: {
+		type: "object",
+		properties: {
+			name: {
+				type: "string",
+				example: "John Doe"
+			}
+		},
+		required: ["name"]
+	},
+	response: {
+		200: {
+			type: "object",
+			properties: {
+				message: {
+					type: "string",
+					example: "Hello John Doe again 🙋‍♂️"
+				}
+			},
+			required: ["message"]
+		}
+	}
+};

package/templates/src/{welcome.js → Tests/welcome.js}

@@ -4,7 +4,7 @@ export default async function handler(req, rep) {
 
 	console.log("GET /welcome");
 	return {
-		message: "Weclome to maxserver 😉",
+		message: "Weclome to maxserver 😉 - Updated",
 	};
 
 }

package/templates/src/Tests/welcome.schema.js

@@ -0,0 +1,17 @@
+export default {
+	summary: "Test get welcome",
+	description: "Returns a friendly welcome message to verify the server is operational.",
+	tags: ["Tests"],
+	response: {
+		200: {
+			type: "object",
+			properties: {
+				message: {
+					type: "string",
+					example: "Weclome to maxserver 😉 - Updated"
+				}
+			},
+			required: ["message"]
+		}
+	}
+};

package/templates/vscode/tasks.json

@@ -1,9 +1,6 @@
 // Comment task in to autostart server on dir open
-/*
-
-
 {
-	"version": "1.0.0",
+	"version": "2.0.0",
 	"tasks": [
 		{
 			"label": "devserver 📟",
@@ -16,8 +13,18 @@
 			"runOptions": {
 				"runOn": "folderOpen"
 			}
+		},
+		{
+			"label": "openBrowser",
+			"type": "shell",
+			"command": "sleep 1; open http://localhost:3000/docs",
+			"presentation": {
+				"reveal": "never",
+				"panel": "shared"
+			},
+			"runOptions": {
+				"runOn": "folderOpen"
+			}
 		}
 	]
-}
-
-*/
+}

package/archive/setupRoutesOld.js

@@ -1,132 +0,0 @@
-
-/**
- * 🚀 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";
-
-
-// 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;
-
-	for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-		if (e.name === "node_modules") continue;
-		if (e.name.startsWith(".")) continue;
-
-		const full = path.join(dir, e.name);
-		if (e.isDirectory()) {
-			walk(full, out);
-			continue;
-		}
-
-		if (!e.name.endsWith(".js")) continue;
-		out.push(full);
-	}
-
-	return out;
-}
-
-
-/**
- * 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 matches = [...text.matchAll(ROUTE_REGEX)];
-
-	if (matches.length === 0) return null;
-
-	// 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;
-	}
-
-	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, url };
-}
-
-
-/**
- * Safe dynamic import that handles Windows paths correctly.
- */
-async function importDefault(file) {
-	return (await import(pathToFileURL(file).href)).default;
-}
-
-
-export async function setupRoutes(app) {
-	const seen = new Map();
-	const root = path.resolve(app.maxserver.routesDir || "src");
-
-	for (const file of walk(root)) {
-		// Skip schema files; they are loaded alongside their route file
-		if (file.endsWith(".schema.js")) continue;
-
-		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(
-				`Duplicate route "${key}" detected:\n` +
-				`1. ${seen.get(key)}\n` +
-				`2. ${file}`
-			);
-		}
-		seen.set(key, file);
-
-		// 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 = {};
-
-		if (fs.existsSync(schemaFile)) {
-			const loaded = await importDefault(schemaFile);
-			// 🛡️ Guard: Ensure export is a valid object before using it
-			if (loaded && typeof loaded === "object") raw = loaded;
-		}
-
-		// ✨ Magic: Extract 'auth' and 'routeOptions' specifically
-		let { auth, routeOptions = {}, ...schema } = raw;
-
-		// Inject 'auth' into config if present (Syntactic Sugar)
-		if (auth !== undefined) {
-			routeOptions = {
-				...routeOptions,
-				config: { ...(routeOptions.config || {}), auth: !!auth },
-			};
-		}
-
-		app[info.method](info.url, { ...routeOptions, schema }, handler);
-	}
-}

package/templates/src/hello.js

@@ -1,14 +0,0 @@
-// POST /hello
-
-export default async function handler(req, rep) {
-
-	console.log("POST /hello");
-
-	return {
-		message: `Hello ${req.body.name} 🙋‍♂️`,
-	};
-}
-
-
-
-// Try POST with and without name, to see how the schema works

package/templates/src/hello.schema.js

@@ -1,36 +0,0 @@
-export default {
-
-	// These 3 fields are for the documentation
-	// Not must have, but your auto generated documentation will be great
-
-	tags: ["Test"],
-	summary: "Post hello",
-	description: "Accepts a name and returns a greeting.",
-
-	body: {
-		type: "object",
-		required: ["name"],
-		properties: {
-			name: {
-				type: "string",
-				example: "Max",
-			},
-		},
-	},
-
-	response: {
-		200: {
-			type: "object",
-			properties: {
-				message: {
-					type: "string",
-					example: "Hello Max",
-				},
-			},
-		},
-	},
-};
-
-// Hint - You don't need to write these ourself
-// Just ask chat gpt or gemini to generate them
-// In docs you will find little instruction for it