@nano-app/backend 0.10.0 → 0.12.0

package/README.md

@@ -4,11 +4,11 @@
 
 Preconfigured Express server with **file-convention routes** and **plugins**: it mounts the base middlewares, discovers your routes, formats every error as JSON, and groups extra endpoints in plugins.
 
-- Node ≥ 20, ESM.
+- Node.js 22.23.4, 24.22.1 or 26.12.1 and newer. ESM only.
 - Optional PostgreSQL layer through your generated Prisma client. Disabled by default: without it no database code is loaded.
 
 ```bash
-npm install @nano-app/backend
+pnpm add @nano-app/backend
 ```
 
 ## Quick start
@@ -24,17 +24,17 @@ src/
 
 ```ts
 // src/app.ts
-import { createNanoApp } from "@nano-app/backend";
+import { createNanoApp } from '@nano-app/backend';
 
 createNanoApp({ port: 3000 });
 ```
 
 ```ts
 // src/routes/health.route.ts
-import { createRoute } from "@nano-app/backend";
+import { createRoute } from '@nano-app/backend';
 
 export default createRoute({
-  GET: async () => ({ success: true, result: { status: "ok" } }),
+  GET: async () => ({ success: true, result: { status: 'ok' } }),
 });
 ```
 
@@ -52,9 +52,9 @@ Each `*.route.ts` under `mainPlugin.routesDir` default-exports an object with th
 
 ```ts
 export default createRoute({
-  expression: "/:id",                                  // → /users/:id
+  expression: '/:id',                                  // → /users/:id
   GET:    async req => ({ success: true, result: { id: req.params.id } }),
-  DELETE: async req => ({ success: true, message: "Deleted" }),
+  DELETE: async req => ({ success: true, message: 'Deleted' }),
 });
 ```
 
@@ -69,6 +69,7 @@ type ApiResponse<T> = {
 };
 ```
 
+- A write returns the item as it is after it in `result`: `POST` the created item, `PUT` the updated item, `DELETE` the deleted item. The frontend keeps what an update returns.
 - Undeclared methods respond `405`.
 - An invalid file is discarded with a warning; the other routes keep working.
 
@@ -85,13 +86,13 @@ Every option is optional.
 | `mainPlugin` | `{ routesDir: "src/routes" }` | Your routes (`routesDir`, relative to `cwd`), `basePath` (e.g. `/api`, no trailing slash) and database: see [Database](#database). |
 | `plugins` | `[]` | Plugins mounted around your routes, in order: see [Plugins](#plugins). |
 
-`packages` accepts `morgan`, `cors`, `helmet`, `compression`, `rateLimit`, `express` (`express.json` options), `urlencoded` and `betterAuth` (off by default: see [Better Auth](#better-auth)). The merge is **per section**: passing one key keeps the others; pass `false`/`undefined` to disable one.
+`packages` accepts `morgan`, `cors`, `helmet`, `compression`, `rateLimit`, `express` (`express.json` options), `urlencoded` and `betterAuth` (off by default: see [Better Auth](#better-auth)). The merge is **per section**: passing one key keeps the others; pass `false` to disable one.
 
 ```ts
 createNanoApp({
-  settings: { "trust proxy": 1 },
+  settings: { 'trust proxy': 1 },
   packages: {
-    cors: { origin: "https://my-app.com" },
+    cors: { origin: 'https://my-app.com' },
     helmet: false,
     rateLimit: { windowMs: 60_000, max: 120 },
   },
@@ -100,10 +101,10 @@ createNanoApp({
 
 ## Database
 
-Off until enabled: at startup nano-app generates the Prisma client of your schema, checks that its tables can be read and passes it to your handlers as their second parameter. **It never modifies your database**: applying the schema (`prisma db push`, `prisma migrate dev`, `prisma migrate deploy`) is up to you, with Prisma.
+Off until enabled: at startup nano-app generates the Prisma client of your schema, checks that its tables can be read and passes it to your handlers as their second parameter. **It never modifies your schemas**: applying them (`prisma db push`, `prisma migrate dev`, `prisma migrate deploy`) is up to you, with Prisma.
 
 ```bash
-npm install prisma @prisma/client @prisma/adapter-pg pg   # prisma too: the startup generates the client
+pnpm add prisma @prisma/client @prisma/adapter-pg pg   # prisma too: the startup generates the client
 ```
 
 ```prisma
@@ -130,8 +131,8 @@ createNanoApp({ mainPlugin: { database: { enabled: true } } });
 
 ```ts
 // src/routes/users.route.ts
-import { createRoute } from "@nano-app/backend";
-import type { PrismaClient } from "../../.nano-app/prisma-clients/app/generated/client";
+import { createRoute } from '@nano-app/backend';
+import type { PrismaClient } from '../../.nano-app/prisma-clients/app/generated/client';
 
 export default createRoute<PrismaClient>({
   GET: async (_req, { db }) => ({ success: true, result: await db!.user.findMany() }),
@@ -157,12 +158,12 @@ export default createRoute<PrismaClient>({
 Users, sign-in and sessions with [Better Auth](https://www.better-auth.com), on your database. Off until `packages.betterAuth` gets its options (everything but `database`: nano-app passes your Prisma client).
 
 ```bash
-npm install better-auth
+pnpm add better-auth
 ```
 
 ```ts
 // src/auth.ts: the options, and an instance only for the Better Auth CLI
-import { betterAuth, type BetterAuthOptions } from "better-auth";
+import { betterAuth, type BetterAuthOptions } from 'better-auth';
 
 export const authOptions = { emailAndPassword: { enabled: true } } satisfies BetterAuthOptions;
 export const auth = betterAuth(authOptions);
@@ -170,8 +171,8 @@ export const auth = betterAuth(authOptions);
 
 ```ts
 // src/app.ts
-import { createNanoApp } from "@nano-app/backend";
-import { authOptions } from "./auth";
+import { createNanoApp } from '@nano-app/backend';
+import { authOptions } from './auth';
 
 createNanoApp({
   packages: { betterAuth: authOptions },
@@ -203,20 +204,20 @@ A plugin is a group of endpoints mounted under a base path. Your routes are moun
 
 ```ts
 // src/plugins/hello/index.ts
-import { createPlugin } from "@nano-app/backend";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { createPlugin } from '@nano-app/backend';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 export default createPlugin((options?: { basePath?: string }) => ({
-  name: "hello",
-  basePath: options?.basePath ?? "/hello",
-  routesDir: resolve(dirname(fileURLToPath(import.meta.url)), "routes"),
+  name: 'hello',
+  basePath: options?.basePath ?? '/hello',
+  routesDir: resolve(dirname(fileURLToPath(import.meta.url)), 'routes'),
 }));
 ```
 
 ```ts
 // src/plugins/hello/routes/index.route.ts  →  /hello
-import { createRoute } from "@nano-app/backend";
+import { createRoute } from '@nano-app/backend';
 
 export default createRoute({
   GET: async () => ({ success: true, result: { ok: true } }),
@@ -225,8 +226,8 @@ export default createRoute({
 
 ```ts
 // src/app.ts
-import { createNanoApp } from "@nano-app/backend";
-import hello from "./plugins/hello";
+import { createNanoApp } from '@nano-app/backend';
+import hello from './plugins/hello';
 
 createNanoApp({ plugins: [hello()] });
 ```
@@ -245,12 +246,12 @@ Two levels. Only the plugin's receives the Express app, so nothing app-wide depe
 
 ```ts
 export default createPlugin((options?: { publicPaths?: string[] }) => ({
-  name: "guard",
-  routesDir: resolve(dirname(fileURLToPath(import.meta.url)), "routes"),
+  name: 'guard',
+  routesDir: resolve(dirname(fileURLToPath(import.meta.url)), 'routes'),
   options: { publicPaths: options?.publicPaths ?? [] },
   callbacks: {
     onMount: async (app, { publicPaths }) => {
-      app.use((req, _res, next) => next(publicPaths.includes(req.path) ? undefined : { status: 401, message: "Unauthorized" }));
+      app.use((req, _res, next) => next(publicPaths.includes(req.path) ? undefined : { status: 401, message: 'Unauthorized' }));
     },
   },
 }));
@@ -260,16 +261,16 @@ The endpoints of one plugin have no guaranteed order: one route's `onInit` must
 
 Everything is mounted on one Express application, in this order: base middlewares → `before` plugins → your routes → `after` plugins → 404 → error handler.
 
-A plugin with a database follows the same rules, with its client in `.nano-app/prisma-clients/<name>`: a plugin of yours points `database.schemaPath` at its schema and you apply it with Prisma. If that folder holds the client of another schema (another plugin with the same name), the startup warns and replaces it. An official plugin of `@nano-app/plugins` needs nothing from you: at startup nano-app applies its migrations to its own `nano_*` schema. See [PLUGINS.md](https://github.com/Nano-Nathan/nano-app/blob/main/PLUGINS.md).
+A plugin with a database follows the same rules, with its client in `.nano-app/prisma-clients/<name>`: a plugin of yours points `database.schemaPath` at its schema and you apply it with Prisma. Two plugins with the same name and a database fail at startup. If that folder holds the client of another schema from an earlier start, the startup warns and replaces it. An official plugin of `@nano-app/plugins` needs nothing from you: at startup nano-app applies its migrations to its own `nano_*` schema. See [PLUGINS.md](https://github.com/Nano-Nathan/nano-app/blob/main/PLUGINS.md).
 
 ## Errors
 
 The framework mounts the 404 and the error handler: an unmatched request becomes a `404`, and anything a handler throws becomes an `ApiResponse`.
 
 ```ts
-throw { status: 409, message: "Already exists" };   // → 409 { success: false, warning: false, message: "Already exists" }
-throw "Field name is required";                     // → 400 { success: false, message: "Field name is required" }
-throw new Error("boom");                            // → 500, logged to stderr
+throw { status: 409, message: 'Already exists' };   // → 409 { success: false, warning: false, message: "Already exists" }
+throw 'Field name is required';                     // → 400 { success: false, message: "Field name is required" }
+throw new Error('boom');                            // → 500, logged to stderr
 GET /unknown                                        // → 404 { success: false, warning: false, message: "/unknown not found" }
 ```
 
@@ -282,7 +283,7 @@ GET /unknown                                        // → 404 { success: false,
 | `createPlugin(creator)` | Types a plugin factory and its options. |
 | `createPluginCallbacks(callbacks)` | Types the callbacks of a plugin (`createPluginCallbacks<PrismaClient>` types `db`), e.g. to keep them in their own file. |
 
-Also exported: the configuration types (`NanoAppConfig`, `PackagesConfig`, `PluginConfig`, `PluginStage`, `MainPluginConfig`, `DatabaseConfig`), the Express `Request` type and the HTTP contract (`ApiResponse`, `ApiPromise`, `QueryParams`, `RouteEntry`, `Handler`, `Handlers`, `NanoObject`) and the callback types (`Params`, `Callbacks`, `PluginCallbacks`).
+Also exported: the `NanoApp` class that `createNanoApp` returns, the configuration types (`NanoAppConfig`, `PackagesConfig`, `PluginConfig`, `PluginStage`, `MainPluginConfig`, `DatabaseConfig`), the Express `Request` type and the HTTP contract (`ApiResponse`, `ApiPromise`, `QueryParams`, `RouteEntry`, `Handler`, `Handlers`, `NanoObject`) and the callback types (`Params`, `Callbacks`, `PluginCallbacks`).
 
 ## Development
 

package/build/index.d.ts

@@ -31,8 +31,9 @@ type Params<DB = any> = Partial<NanoObject & {
   /** `{ user, session }` of Better Auth, on the routes behind its guard */
   session?: NanoObject;
 }>;
-/** Endpoint handlers */
+/** Endpoint handler */
 type Handler<DB> = (req: Request$1, params: Params<DB>) => ApiPromise;
+/** Endpoint handlers, one per HTTP method */
 type Handlers<DB = any> = {
   GET?: Handler<DB>;
   POST?: Handler<DB>;
@@ -40,9 +41,11 @@ type Handlers<DB = any> = {
   DELETE?: Handler<DB>;
   QUERY?: Handler<DB>;
 };
-/** Callbacks */
+/** Callback run with the params */
 type Callback<DB> = (params: Params<DB>) => Promise<void>;
+/** Callback run before a method, with its request */
 type CallbackMethod<DB> = (req: Request$1, method: string, params: Params<DB>) => Promise<NanoObject>;
+/** Callback run with the Express app */
 type CallbackMount<DB> = (app: Express, params: Params<DB>) => Promise<void>;
 /** Callbacks of an endpoint. They never receive the app: what affects the whole app goes in the plugin's onMount */
 type Callbacks<DB = any> = {
@@ -79,7 +82,7 @@ type DatabaseConfig = {
 type PluginStage = 'before' | 'after';
 /** Plugin configuration: a group of endpoints */
 type PluginConfig<Options = NanoObject> = {
-  /** Name of the plugin, same as his database (If have one) */
+  /** Name of the plugin, also the name of its database when it has one */
   name: string;
   /** Directory used to discover the `*.route.ts` files */
   routesDir: string;

package/build/index.js

@@ -13,12 +13,7 @@ import { createJiti } from "jiti";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 //#region ../core/const.ts
-/** Package of the official plugins: only its schemas may declare nano_* */
-const OFFICIAL_PLUGINS = "@nano-app/plugins";
-/** Error when the database URL is missing, at startup and on `nano-app push` */
-const MISSING_DATABASE_URL = "[nano-app] [ERROR] The DATABASE_URL environment variable is not defined.";
-//#endregion
-//#region ../core/loader/Validator.ts
+/** HTTP methods a route can handle */
 const HTTP_METHODS = [
 	"GET",
 	"POST",
@@ -26,6 +21,12 @@ const HTTP_METHODS = [
 	"DELETE",
 	"QUERY"
 ];
+/** Package of the official plugins: only its schemas may declare nano_* */
+const OFFICIAL_PLUGINS = "@nano-app/plugins";
+/** Error when the database URL is missing at startup */
+const MISSING_DATABASE_URL = "[nano-app] [ERROR] The DATABASE_URL environment variable is not defined.";
+//#endregion
+//#region ../core/loader/Validator.ts
 const STORE_TYPES = ["app", "api"];
 /** Checks the consumer's files: invalid ones are warned about and discarded */
 var Validator = class Validator {
@@ -44,15 +45,12 @@ var Validator = class Validator {
 		if (oEntry && typeof oEntry === "object") return true;
 		return Validator.warn(sFilePath, "the default export is not an object.");
 	}
-	/**
-	* Type guard for a `*.route.ts` entry.
-	*/
+	/** Type guard for a `*.route.ts` entry */
 	static isRoute(oEntry, sFilePath) {
 		if (!Validator.isObject(oEntry, sFilePath)) return false;
-		const oRoute = oEntry;
-		if (oRoute.expression && typeof oRoute.expression !== "string") return Validator.warn(sFilePath, "\"expression\" must be a string.");
-		for (const sMethod of HTTP_METHODS) if (oRoute[sMethod] && typeof oRoute[sMethod] !== "function") return Validator.warn(sFilePath, `"${String(sMethod)}" must be a function.`);
-		if (!HTTP_METHODS.some((sMethod) => oRoute[sMethod])) return Validator.warn(sFilePath, "defines no HTTP method.");
+		if (oEntry.expression && typeof oEntry.expression !== "string") return Validator.warn(sFilePath, "\"expression\" must be a string.");
+		for (const sMethod of HTTP_METHODS) if (oEntry[sMethod] && typeof oEntry[sMethod] !== "function") return Validator.warn(sFilePath, `"${sMethod}" must be a function.`);
+		if (!HTTP_METHODS.some((sMethod) => oEntry[sMethod])) return Validator.warn(sFilePath, "defines no HTTP method.");
 		return true;
 	}
 	/** Type guard for a `*.store.ts` entry */
@@ -61,11 +59,10 @@ var Validator = class Validator {
 		if (!STORE_TYPES.includes(oEntry.type)) return Validator.warn(sFilePath, `its type must be "app" or "api".`);
 		if (oEntry.data !== void 0 && (!oEntry.data || typeof oEntry.data !== "object")) return Validator.warn(sFilePath, "\"data\" must be an object.");
 		if (oEntry.headers !== void 0 && (!Validator.isObject(oEntry.headers, sFilePath) || Object.values(oEntry.headers).some((sValue) => typeof sValue !== "string"))) return Validator.warn(sFilePath, "\"headers\" must be an object of strings.");
+		if (oEntry.auth !== void 0 && typeof oEntry.auth !== "string") return Validator.warn(sFilePath, "\"auth\" must be a string: the base path of Better Auth.");
 		return true;
 	}
-	/**
-	* Type guard for a `.prisma` entry: the contents of the file, without comments.
-	*/
+	/** Type guard for a `.prisma` entry: the contents of the file, without comments */
 	static isPrisma(oEntry, sFilePath) {
 		if (typeof oEntry !== "string") return Validator.warn(sFilePath, "the contents are not a string.");
 		const sProvider = oEntry.match(/datasource\s+\w+\s*\{[^}]*provider\s*=\s*["']([^"']+)["']/s)?.[1];
@@ -90,6 +87,7 @@ var Validator = class Validator {
 //#region ../core/loader/FileReader.ts
 /** Reads and loads files from disk, resolved from `cwd` */
 var FileReader = class {
+	/** Loader of the consumer's modules; the Prisma runtime is loaded natively */
 	static oJiti = createJiti(import.meta.url, { nativeModules: ["@prisma/client"] });
 	/** Loads a module via jiti */
 	static async loadModule(sFilePath, oOptions = {}) {
@@ -118,7 +116,8 @@ var FileReader = class {
 var Formatter = class {
 	/** Message of anything thrown: its `message` when it has one, else the value itself */
 	static error(oError) {
-		return String(oError?.message ?? oError);
+		if (oError && typeof oError === "object" && "message" in oError) return String(oError.message ?? oError);
+		return String(oError);
 	}
 	/** Formats a date for the request log, in UTC: `2026-10-19 12:03:10` */
 	static logDate(oDate = /* @__PURE__ */ new Date()) {
@@ -178,7 +177,8 @@ var Endpoint = class {
 	createHandler(oParams) {
 		return (oReq, oRes, fnNext) => {
 			const sMethod = oReq.method.toUpperCase();
-			const fnMethod = this.oMethods[sMethod];
+			const sHandled = HTTP_METHODS.find((sHttpMethod) => sHttpMethod === sMethod);
+			const fnMethod = sHandled && this.oMethods[sHandled];
 			if (!fnMethod) return fnNext({
 				status: 405,
 				message: `Method ${sMethod} not implemented`
@@ -320,7 +320,7 @@ var Prisma = class {
 		try {
 			sCli = createRequire(`${process.cwd()}/`).resolve("prisma/build/index.js");
 		} catch {
-			throw new Error(`[nano-app] [ERROR] The database "${sName}" needs Prisma: install the prisma package.`);
+			throw new Error(`[nano-app] [ERROR] The database "${sName}" needs Prisma. Run \`pnpm add prisma\`.`);
 		}
 		try {
 			execFileSync(process.execPath, [sCli, ...aArgs], {
@@ -331,9 +331,8 @@ var Prisma = class {
 				stdio: "pipe"
 			});
 		} catch (oError) {
-			const oFailed = oError;
-			const sOutput = `${oFailed.stderr ?? ""}${oFailed.stdout ?? ""}`.trim() || Formatter.error(oError);
-			throw new Error(`[nano-app] [ERROR] prisma ${aArgs[0]} failed for "${sName}": ${sOutput}`);
+			const sOutput = oError instanceof Error && "stderr" in oError && "stdout" in oError ? `${oError.stderr}${oError.stdout}`.trim() : "";
+			throw new Error(`[nano-app] [ERROR] prisma ${aArgs[0]} failed for "${sName}": ${sOutput || Formatter.error(oError)}`);
 		}
 	}
 };
@@ -394,8 +393,7 @@ var Database = class {
 			if (dirname(sDir) === sDir) return false;
 			sDir = dirname(sDir);
 		}
-		const { name } = JSON.parse(readFileSync(join(sDir, "package.json"), "utf-8"));
-		return name === OFFICIAL_PLUGINS;
+		return JSON.parse(readFileSync(join(sDir, "package.json"), "utf-8")).name === OFFICIAL_PLUGINS;
 	}
 };
 //#endregion
@@ -432,7 +430,7 @@ var Plugin = class {
 //#region src/app/config.ts
 /** Initial application configuration */
 const INITIAL_CONFIG = {
-	/** Initial application configuration */
+	/** Application port */
 	port: 3e3,
 	/** Application listener */
 	listener: () => {},
@@ -488,9 +486,14 @@ function deepMerge(oDefault, oValue) {
 	});
 	return Object.fromEntries(aKeys.map((sKey) => [sKey, deepMerge(oDefault[sKey], oValue[sKey])]));
 }
+/** Whether a merged configuration kept the plain object of the initial one */
+function isMergedConfig(oValue) {
+	return isPlainObject(oValue);
+}
 /** Merges the consumer configuration over the initial one; the main plugin is always named "app" */
 function mergeConfig(oConfig = {}) {
 	const oMerged = deepMerge(INITIAL_CONFIG, oConfig);
+	if (!isMergedConfig(oMerged)) throw new Error("[nano-app] [ERROR] The configuration of createNanoApp must be an object.");
 	return {
 		...oMerged,
 		mainPlugin: {
@@ -501,6 +504,10 @@ function mergeConfig(oConfig = {}) {
 }
 //#endregion
 //#region src/app/errors.ts
+/** Whether anything thrown is an object, read as a HandlerError */
+function isHandlerError(oError) {
+	return typeof oError === "object" && oError !== null;
+}
 /** Normalizes anything thrown by a handler into an ApiResponse plus its status */
 function normalize(oError) {
 	if (typeof oError === "string") return {
@@ -510,7 +517,7 @@ function normalize(oError) {
 			message: oError
 		}
 	};
-	const { status, message, warning } = oError ?? {};
+	const { status, message, warning } = isHandlerError(oError) ? oError : {};
 	return {
 		status: status ?? 500,
 		body: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/backend",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Express server with file-convention routes, plugins and an optional PostgreSQL layer",
   "type": "module",
   "main": "build/index.js",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "dependencies": {
     "compression": "^1.8.2",