maxserver 1.0.1 → 2.1.0

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Max Matinpalo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/bin/init.js

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { execSync } from "child_process";
-
-
-function main() {
-	const { projectName, targetDir, templateDir } = resolveArgs();
-
-	if (fs.existsSync(targetDir)) {
-		console.error(`❌ Error: Directory "${projectName}" already exists.`);
-		process.exit(1);
-	}
-
-	try {
-		console.log(`🚀 Setting up "${projectName}"`);
-		fs.cpSync(templateDir, targetDir, { recursive: true });
-
-		fixDotfiles(targetDir);
-		patchPackageJson(targetDir, projectName);
-
-		process.chdir(targetDir);
-		console.log("📦 Installing maxserver");
-		execSync("npm install maxserver@latest", { stdio: "inherit" });
-
-		console.log(`\n✅ Install complete\n\n->\n\tcd ${projectName}\n\tnpm run dev\n`);
-	} catch (err) {
-		console.error("❌ Init failed:", err.message);
-		process.exit(1);
-	}
-}
-
-
-function resolveArgs() {
-	const base = path.dirname(fileURLToPath(import.meta.url));
-	const name = process.argv[2] || "maxserver";
-
-	return {
-		projectName: name,
-		targetDir: path.resolve(process.cwd(), name),
-		templateDir: path.resolve(base, "../templates")
-	};
-}
-
-
-/**
- * Renames template files to dotfiles and clones vscode settings.
- */
-function fixDotfiles(dir) {
-	// 1. Standard dotfile renames
-	for (const f of ["env", "gitignore"]) {
-		const src = path.join(dir, f);
-		if (fs.existsSync(src)) fs.renameSync(src, path.join(dir, "." + f));
-	}
-
-	// 2. Specialized vscode handling (Root and src)
-	const vscodeSrc = path.join(dir, "vscode");
-
-	if (fs.existsSync(vscodeSrc)) {
-		const srcDir = path.join(dir, "src");
-
-		// Ensure src/ exists before cloning settings into it
-		if (!fs.existsSync(srcDir)) fs.mkdirSync(srcDir);
-
-		// Copy to src/.vscode
-		fs.cpSync(vscodeSrc, path.join(srcDir, ".vscode"), { recursive: true });
-
-		// Rename root vscode to .vscode
-		fs.renameSync(vscodeSrc, path.join(dir, ".vscode"));
-	}
-}
-
-
-function patchPackageJson(dir, name) {
-	const pkgPath = path.join(dir, "package.json");
-	if (!fs.existsSync(pkgPath)) return;
-
-	let content = fs.readFileSync(pkgPath, "utf8");
-	content = content.replace(/__NAME__/g, name);
-	fs.writeFileSync(pkgPath, content);
-}
-
-
-main();

package/bin/watcher.js

@@ -1,48 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from "node:child_process";
-import fs from "node:fs";
-
-
-/**
- * maxserver-watcher
- *
- * A zero-config minimal development server watcher.
- * - Watches the current project root recursively.
- * - Restarts the node process on .js/.json changes.
- * - Automatically loads .env if present via --env-file.
- * - Ignores node_modules and hidden files.
- */
-
-
-// Get entry file from args or default to server.js
-const entry = process.argv[2] || "server.js";
-let child;
-
-function start() {
-	const args = [];
-	if (fs.existsSync(".env")) args.push("--env-file=.env");
-	args.push(entry);
-
-	// Spawn the node process and share the console
-	child = spawn("node", args, { stdio: "inherit" });
-}
-
-function restart() {
-	console.clear();
-	//console.log(`devserver restart`);
-	if (child) child.kill();
-	start();
-}
-
-
-fs.watch(".", { recursive: true }, (event, file) => {
-	if (!file) return;
-	if (file.includes("node_modules")) return;
-	if (file.startsWith(".")) return;
-	if (!file.endsWith(".js") && !file.endsWith(".json")) return;
-
-	//console.log("\nupdated: ", file);
-	restart();
-});
-
-restart();

package/index.d.ts

@@ -1,68 +0,0 @@
-import "fastify";
-import "@fastify/jwt";
-
-declare function maxserver(...args: any[]): any;
-export default maxserver;
-
-declare global {
-
-	var global: typeof globalThis;
-
-	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. */
-	var db: import("mongodb").Db;
-
-	/**
-	 * 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 message The specific failure reason returned in the JSON body.
-	 */
-	var createError: (code: number, message: string) => Error;
-}
-
-declare module "fastify" {
-	interface FastifyInstance {
-		maxserver: {
-			env?: string;
-			cors?: string | boolean | RegExp | Array<string | RegExp>;
-			secret?: string;
-			mongodb?: string;
-			static?: string;
-			errorLogger?: boolean;
-		};
-	}
-
-	interface FastifyRequest {
-		userId: string | null;
-	}
-
-	interface FastifyContextConfig {
-		auth?: boolean;
-	}
-
-	interface RouteShorthandOptions {
-		config?: FastifyContextConfig;
-	}
-}
-
-declare module "@fastify/jwt" {
-	interface FastifyJWT {
-		user: {
-			sub?: string;
-			userId?: string;
-			userid?: string;
-			id?: string;
-			[key: string]: unknown;
-		};
-	}
-}
-
-export { };

package/src/devSounds.js

@@ -1,35 +0,0 @@
-// Development sounds to make api development even more fun 😃
-
-import { exec } from "child_process";
-
-export async function setupDevSounds(app) {
-	if (!app.maxserver.sounds) return;
-	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";
-
-	let lastPlayed = 0;
-
-	const play = file => {
-		const now = Date.now();
-		if (now - lastPlayed < 1000) return;
-		lastPlayed = now;
-		exec(`afplay "${file}" >/dev/null 2>&1 &`);
-	};
-
-	app.addHook("onResponse", async (req, reply) => {
-		const ct = String(reply.getHeader("content-type") || "").toLowerCase();
-		const disabled = req.routeOptions?.config?.devSound === false;
-		const trigger = ct && ct.includes("application/json") && !disabled;
-
-		if (req.url === "/docs/openapi.json") return;
-
-		if (trigger) {
-			const code = reply.statusCode;
-			if (code < 400) play(ok);
-			else play(err);
-		}
-	});
-}

package/src/getAddress.js

@@ -1,46 +0,0 @@
-import os from "node:os";
-
-
-/**
- * When listening on all interfaces (0.0.0.0), Node returns "0.0.0.0".
- * This is a setting, not a valid URL for other devices.
- * So we try hunt down the actual LAN IP to print the real address on which server can be accessed
- */
-
-
-function getLanIp() {
-	const nets = os.networkInterfaces();
-
-	for (const name of Object.keys(nets)) {
-		for (const net of (nets[name] || [])) {
-			if (net?.family === "IPv4" && !net.internal) return net.address;
-		}
-	}
-
-	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/setup.js

@@ -1,104 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import cors from "@fastify/cors";
-import jwt from "@fastify/jwt";
-import cookie from "@fastify/cookie";
-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,
-		frameguard: false,
-		crossOriginResourcePolicy: {
-			policy: "cross-origin"
-		}
-	});
-}
-
-export async function setupCors(app) {
-	const isProd = app.maxserver.env === "production";
-	let origin = app.maxserver.cors ?? "*";
-
-	if (origin === "*" && !isProd)
-		origin = true;
-
-	if (isProd && (origin === "*" || origin === true))
-		app.log.warn("CORS: allowing all origins in production with credentials is risky");
-
-	await app.register(cors, {
-		origin,
-		credentials: true,
-		methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
-	});
-}
-
-export async function setupCookie(app) {
-	await app.register(cookie, {
-		secret: app.maxserver.secret,
-		hook: "onRequest"
-	});
-}
-
-export async function setupMongo(app) {
-	const url = app.maxserver.mongodb;
-	if (!url) return;
-	await app.register(mongodb, { url });
-
-	const { ObjectId, db } = app.mongo;
-	global.oid = id => new ObjectId(id);
-	global.db = db;
-}
-
-export async function setupJwt(app) {
-	await app.register(jwt, {
-		secret: app.maxserver.secret,
-		cookie: { cookieName: "token" }
-	});
-
-	app.addHook("preHandler", async function (req) {
-		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;
-
-	if (typeof dir !== "string") {
-		console.error("❌ maxserver.static must be a string path");
-		return;
-	}
-
-	const abs = path.resolve(dir);
-	if (!fs.existsSync(abs)) {
-		console.error(`❌ maxserver.static not found: ${abs}`);
-		return;
-	}
-
-	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

@@ -1,78 +0,0 @@
-import swagger from "@fastify/swagger";
-import apiReference from "@scalar/fastify-api-reference";
-
-
-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" },
-				},
-			},
-		},
-		// Only consider for documentation routes which have a schema
-		transform: ({ schema, url }) => {
-			const isDefined = schema && (schema.summary || schema.response || schema.body);
-			if (!isDefined) return { schema: { hide: true }, url };
-			return { schema, url };
-		}
-	});
-
-	// not needed, the scalar extension provides it by default on /docs/openapi.json
-	// app.get("/openapi.json", {schema}, () => app.swagger());
-
-
-	if (app.maxserver.docs !== false)
-		await app.register(apiReference, {
-			"routePrefix": "/docs",
-			"openapi": true,
-			"configuration": {
-				hideSearch: true,
-				hiddenClients: true,
-				hideClientButton: true,
-				telemetry: false,
-				persistAuth: true,
-				showDeveloperTools: "never",
-				//"expandAllModelSections": true,
-				// operationsSorter: "alpha",
-				orderSchemaPropertiesBy: "preserve",
-				metaData: {
-					title: "Server",
-				},
-				authentication: {
-					preferredSecurityScheme: 'bearerAuth',
-					apiKey: { token: "" }
-				},
-				customCss: `
-				.darklight-reference a[href*="scalar.com"] {
-							 display: none !important;
-				},
-				.text-sidebar-c-2 {
-					display: none !important;
-				}`,
-				...app.maxserver.scalar
-			}
-		});
-
-	app.addHook("onRoute", (route) => {
-		const auth = route.config?.auth;
-		if (!auth) return;
-		route.schema ||= {};
-		route.schema.security ||= [{ bearerAuth: [] }, { cookieAuth: [] }];
-	});
-}
-
-
-
-

package/src/setupRoutes.js

@@ -1,164 +0,0 @@
-/**
- * 🚀 AUTO-LOADER
- * Scans src/ for files with "// METHOD /url" comments.
- * Automatically registers them as Fastify routes.
- * Also registers lonely .schema.js files as global shared schemas.
- */
-
-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.
- */
-function walk(dir, out = []) {
-	if (!fs.existsSync(dir)) return out;
-
-	for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-		if (e.name === "node_modules" || e.name.startsWith(".")) continue;
-
-		const full = path.join(dir, e.name);
-		if (e.isDirectory()) {
-			walk(full, out);
-			continue;
-		}
-
-		if (e.name.endsWith(".js")) out.push(full);
-	}
-
-	return out;
-}
-
-/**
- * Extracts method and URL from the file's "magic comment".
- */
-function getRoute(file) {
-	const text = fs.readFileSync(file, "utf8");
-	const matches = [...text.matchAll(ROUTE_REGEX)];
-
-	if (matches.length === 0) return null;
-
-	if (matches.length > 1) {
-		console.warn(`⚠️ Ignored "${file}": Only 1 route allowed per file.`);
-		return null;
-	}
-
-	const m = matches[0];
-	return {
-		method: m[1].toLowerCase(),
-		url: "/" + m[2].trim().replace(/^\/+/, "")
-	};
-}
-
-export async function setupRoutes(app) {
-	const root = path.resolve(app.maxserver.routesDir || "src");
-	const files = walk(root);
-
-	// 1. Pass One: Register Named Exports Globally
-	const globals = new Map();
-	for (const file of files) {
-		if (file.endsWith(".schema.js")) continue;
-
-		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: 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);
-	}
-
-	// 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 mod = await import(pathToFileURL(file).href);
-		const handler = mod.default;
-		if (typeof handler !== "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 import(pathToFileURL(schemaFile).href)).default;
-			if (loaded && typeof loaded === "object") raw = loaded;
-		}
-
-		let { auth, order = 999, routeOptions = {}, ...schema } = raw;
-
-		if (auth !== undefined) {
-			routeOptions = {
-				...routeOptions,
-				config: { ...(routeOptions.config || {}), auth: !!auth },
-			};
-		}
-
-		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/gitignore

@@ -1 +0,0 @@
-node_modules

package/templates/jsconfig.json

@@ -1,23 +0,0 @@
-{
-	"compilerOptions": {
-		"checkJs": true,
-		"module": "ES2020",
-		"target": "ES2020",
-		"moduleResolution": "bundler",
-		"strict": false,
-		"noUnusedParameters": false,
-		"noUnusedLocals": false,
-		"noImplicitAny": false,
-		"skipLibCheck": true,
-		"types": [
-			"node",
-			"maxserver"
-		]
-	},
-	"include": [
-		"src"
-	],
-	"exclude": [
-		"node_modules",
-	],
-}

package/templates/package.json

@@ -1,13 +0,0 @@
-{
-	"name": "__NAME__",
-	"version": "0.1.0",
-	"description": "",
-	"main": "server.js",
-	"scripts": {
-		"start": "node server.js",
-		"dev": "maxserver-watcher"
-	},
-	"type": "module",
-	"private": "true",
-	"dependencies": {}
-}

package/templates/src/ai/BASE

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