maxserver 0.1.24 → 0.1.30

package/README.md

@@ -1,6 +1,5 @@
 # maxserver
-Nothing Special.  
-Just a Node server setup based on **Fastify** to speed up backend development.  
+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
@@ -32,7 +31,7 @@ export default server;
 
 ## ⚙️ 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.
+If you define options in env, use all upper case letters.  
 Any fastify options can be passed to maxserver() too.
 
 
@@ -40,8 +39,8 @@ Any fastify options can be passed to maxserver() too.
 | :--- | :--- | :--- |
 | `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` |
+| `cors` | `*` | 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 |
@@ -50,29 +49,15 @@ Any fastify options can be passed to maxserver() too.
 
 <br>
 
-## 🗂️ Project Structure 
-Our golden rule: **1 route = 1 handler file + 1 schema file**
 
-Example:
+## 🤖 Auto Routing
+Routes are auto registered based on one small comment per file:  
 
 ```
-src/
-	users/
-	teams/
-	forms/
-		hello.js
-		hello.schema.js
-	...
+// METHOD /path 
 ```
 <br>
 
-## 🤖 Auto Routing
-
-To auto-register routes, simple add a comment of the form:  
-**// METHOD /path**  
-**// GET /user**  
-**// POST /feedback/something**  
-...
 
 ```js
 // GET /hello
@@ -87,22 +72,33 @@ export default async function handler(req, rep) {
 }
 ```
 <br>
-  
-And remember to use default export for your handler.
-If you don't want to autoregister some routes, then simply don't add that magic comment 😃
-That's it.
-
 
+Doesn't matter how nested your path is or how many params,  
+It always works this simple and you are free to position your files the way you like.  
+If you don't want to autoregister some files, then simply don't add that magic comment 😃
 <br>
 <br>
+```
+// GET /teams/:teamid  
+// PATCH /forms/:formId/questions/:questionId
+...   
+```
+<br/>
 
+### 3 RULES
+1. Add magic comment
+2. Default export handler
+3. One handler per file 
 
-## 🧾 Schemas
-Create a sibling file ending with **`.schema.js`**, so it will be auto registered. For example: **hello.js** and **hello.schema.js** 
+<br>
 
-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.
 
+## 🧾 Schemas
+Files ending with **`.schema.js`** will be auto registered.  
+For example: **hello.js** and **hello.schema.js**  
 
+Besides the basic validation fields we can set fields like `tags`, `summary` and description,  
+which will appear in the docs.
 
 
 ```js
@@ -126,38 +122,30 @@ export default {
 };
 ```
 
-You will find comlete examples in template folder.  
-**‼️ Important use export default**
+**‼️ Important use export default**  
+Some examples in the template folder.
 
-<br>
-
-## 🛠️ Route Options
-Though we don't mostly register routes manually, we don't set route options on the register call.  
-If needed, you can wether register that route manually or just set them on the schema.
 
-```js
-// Inside schema
+### MODELS
+You can also auto register **models** (schemas which are shared between multiple routes).  
+For example `User.schema.js`. It "magically" understand the difference betwen route specific
+schema or generic model, by looking if a sibling file exist or not 😉
 
-export default {
-	routeOptions: {
-		config: {
-			preHandler: ...
-		},
-	},
-	...
-```
+<br>
 
 
-<br>
 
 ## 📚 API Docs
-
 Open in your browser **`localhost:3000/docs`**  
-OpenAPI JSON: **`/openapi.json`**
+You should find all your routes well documented.  
+And you can also easily test any route.
 
 <br>
 
 
+
+
+
 ## 🔐 Authentication
 JWT header and cookie based auth is preconfigured.  
 To enable auth for a route set in it's schema **auth = true**  
@@ -171,6 +159,23 @@ export default {
 };
 ```
 
+## 🛠️ Route Options
+Though we don't mostly register routes manually, we don't set route options on the register call.  
+If needed, you can wether register that route manually or just set them on the schema.
+
+```js
+// Inside schema
+
+export default {
+	routeOptions: {
+		config: {
+			preHandler: ...
+		},
+	},
+	...
+```
+
+<br>
 <br>
 
 ## 🍃 MongoDB
@@ -210,8 +215,28 @@ 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>
+
+## Todo
+- document how to add fastify hooks
+- document how to pass scalar options
+- more example and best practises
+- document project setup with npx
+- npx option, atm devserver macos only
+- unit tests
+
+```
+I am just starting to publish packages on github / npm.  
+Still not sure if it's worth the time 😃
+
+If anyone else than me and bots is using this package,
+just follow me on github and I will improve it.
+
+https://github.com/max-matinpalo
+
+```

package/package.json

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

package/src/devSounds.js

@@ -20,9 +20,15 @@ export async function setupDevSounds(app) {
 
 	app.addHook('onResponse', async (req, reply) => {
 
-		// Test fix, that sound not plays for static served 😃
+		// Dev sounds only for api requests - not for static served files 😃
 		const ct = String(reply.getHeader('content-type') || '').toLowerCase();
-		if (ct && ct.includes('application/json')) {
+		const disabled = req.routeOptions?.config?.devSound === false;
+		let 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) {
 			const code = reply.statusCode;
 			if (code < 400) play(ok);
 			else play(err);

package/src/index.js

@@ -17,6 +17,8 @@ import { setupDevSounds } from "./devSounds.js";
 
 export default async function maxserver(config = {}) {
 
+	console.log("local one running 3");
+
 	const {
 
 		// maxserver options
@@ -71,6 +73,7 @@ export default async function maxserver(config = {}) {
 		console.log('Server running at ', getAddress(this));
 	});
 
+	await setupDevSounds(app);
 	await setupCookie(app);
 	await setupHelmet(app);
 	await setupCors(app);
@@ -79,7 +82,7 @@ export default async function maxserver(config = {}) {
 	await setupStatic(app);
 	await setupDocs(app);
 	await setupRoutes(app);
-	await setupDevSounds(app);
+
 
 	global.createError = function (code, message) {
 		const err = new Error(message);

package/src/setupDocs.js

@@ -2,7 +2,7 @@ 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.",
@@ -27,6 +27,7 @@ const schema = {
 		}
 	}
 };
+*/
 
 
 
@@ -53,8 +54,9 @@ export async function setupDocs(app) {
 		},
 	});
 
+	// not needed, the scalar extension provides it by default on /docs/openapi.json
+	// app.get("/openapi.json", {schema}, () => app.swagger());
 
-	app.get("/openapi.json", { schema }, () => app.swagger());
 
 	if (app.maxserver.docs !== false)
 		await app.register(apiReference, {
@@ -67,6 +69,7 @@ export async function setupDocs(app) {
 				telemetry: false,
 				persistAuth: true,
 				showDeveloperTools: "never",
+				//"expandAllModelSections": true,
 				operationsSorter: "alpha",
 				orderSchemaPropertiesBy: "preserve",
 				metaData: {

package/src/setupRoutes.js

@@ -65,23 +65,6 @@ export async function setupRoutes(app) {
 	const root = path.resolve(app.maxserver.routesDir || "src");
 	const files = walk(root);
 
-	/*
-	// Old one which only graps default exports
-
-	// 1. Pass One: Register Global Schemas (Lonely .schema.js files)
-	for (const file of files) {
-		if (file.endsWith(".schema.js")) {
-			const hasHandler = fs.existsSync(file.replace(".schema.js", ".js"));
-
-			if (!hasHandler) {
-				const schema = await importDefault(file);
-				if (schema?.$id) app.addSchema(schema);
-			}
-		}
-	}
-	*/
-
-
 	// 1. Pass One: Register Global Schemas (Lonely .schema.js files)
 	for (const file of files) {
 		// Only process if no matching handler file exists
@@ -94,7 +77,14 @@ export async function setupRoutes(app) {
 		}
 	}
 
-	// 2. Pass Two: Register Routes
+	// 2. Pass Two: Auto-register hooks
+	for (const file of files) {
+		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();
 	for (const file of files) {
 		if (file.endsWith(".schema.js")) continue;

package/templates/package.json

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

package/TODO.md

@@ -1,4 +0,0 @@
-- get rules.md file for ai (lost atm)
-- add example for db usage
-- unity tests for each config option
-