@nano-app/backend 0.9.0 → 0.11.0

package/README.md

@@ -1,12 +1,14 @@
 # @nano-app/backend
 
+[![backend](https://img.shields.io/npm/v/@nano-app/backend?label=backend)](https://www.npmjs.com/package/@nano-app/backend)
+
 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 ≥ 22, ESM.
 - 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
@@ -22,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' } }),
 });
 ```
 
@@ -50,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' }),
 });
 ```
 
@@ -83,13 +85,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) and `urlencoded`. 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`/`undefined` 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 },
   },
@@ -101,7 +103,7 @@ createNanoApp({
 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.
 
 ```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
@@ -128,8 +130,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() }),
@@ -143,33 +145,78 @@ export default createRoute<PrismaClient>({
 
 - Each key falls back to its default, so `{ enabled: true }` is enough with the default layout.
 - The client lives in `.nano-app/prisma-clients/app/` (add `.nano-app/` to `.gitignore`). It is generated again only when the schema changes. Do not run `prisma generate`: a second client would be out of sync.
-- `npx nano-app generate` does what the startup does, without starting: for your editor's types, or for the build when the filesystem is read-only in production.
+- The client exists after the first startup: start the app once before your editor or `tsc` can import its types. In a container, `.nano-app/` must be writable.
 - Startup fails if `DATABASE_URL` is missing, the schema is not a valid PostgreSQL schema, or a table or column of a model cannot be read. The message says which: apply your schema with Prisma and start again.
 - The `nano_` prefix is reserved for the official plugins (`@nano-app/plugins`): a datasource schema of yours starting with it fails the startup.
 - Pass your generated `PrismaClient` to `createRoute<PrismaClient>` to type `db`; otherwise it is `any`, and without an enabled database `undefined`.
 - For several PostgreSQL schemas, declare `schemas = ["public", "billing"]` in the datasource and `@@schema("billing")` on each model; one client covers them all.
 - Prisma is loaded only when your database or a mounted plugin's is enabled.
 
+## Better Auth
+
+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
+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';
+
+export const authOptions = { emailAndPassword: { enabled: true } } satisfies BetterAuthOptions;
+export const auth = betterAuth(authOptions);
+```
+
+```ts
+// src/app.ts
+import { createNanoApp } from '@nano-app/backend';
+import { authOptions } from './auth';
+
+createNanoApp({
+  packages: { betterAuth: authOptions },
+  mainPlugin: { database: { enabled: true } },
+});
+```
+
+Its tables are yours, like the rest of your schema. Add its models with its CLI, then apply them with Prisma; run both again when you change the options:
+
+```bash
+npx auth generate --config src/auth.ts --adapter prisma --dialect postgresql --output src/prisma/schema.prisma
+npx prisma migrate dev
+```
+
+- It needs the database: `packages.betterAuth` without `mainPlugin.database.enabled` fails at startup.
+- Startup also fails if your schema lacks a model the options need (`user`, `session`, ...), naming them.
+- Its endpoints are mounted with your routes, at its `basePath` (default `/api/auth`), and stay public.
+- Every route of yours and of the `after` plugins needs a session: without one, 401. The `before` plugins stay public (a landing, an about page).
+- Handlers and `onBefore` receive the session in `params.session` (`{ user, session }`).
+- Sign-up works as Better Auth sets it: with `emailAndPassword` anyone can sign up and reach your routes. Close it with `disableSignUp: true`, or check roles in your handlers.
+- Relate your models to `User` in the same schema, as any Prisma relation. Extra user fields go in its `user.additionalFields`.
+- With several PostgreSQL schemas, add `@@schema(...)` to the generated models.
+- Set `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` in the environment, as Better Auth asks.
+- Better Auth is loaded only when it is on.
+
 ## Plugins
 
-A plugin is a group of endpoints mounted under a base path. Your routes are mounted as one (named `app`). The official plugins are in [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md). You write one with `createPlugin` and list it in `plugins`. Nothing is mounted unless you list it. Official plugins that have tables (like `auth`) ship their own migrations: nano-app applies them at startup, each in its `nano_*` schema. That is the only change it makes to your database.
+A plugin is a group of endpoints mounted under a base path. Your routes are mounted as one (named `app`). The official plugins are in [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md). You write one with `createPlugin` and list it in `plugins`. Nothing is mounted unless you list it. Official plugins that have tables ship their own migrations: nano-app applies them at startup, each in its `nano_*` schema. That is the only change it makes to your database.
 
 ```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 } }),
@@ -178,8 +225,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()] });
 ```
@@ -198,12 +245,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' }));
     },
   },
 }));
@@ -220,9 +267,9 @@ A plugin with a database follows the same rules, with its client in `.nano-app/p
 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" }
 ```
 
@@ -235,7 +282,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

@@ -3,6 +3,7 @@ import { CorsOptions } from "cors";
 import { Options } from "express-rate-limit";
 import "dotenv/config";
 import "jiti";
+import { BetterAuthOptions } from "better-auth";
 //#region ../core/types/api.d.ts
 /** API response */
 type ApiResponse<T = any> = {
@@ -13,12 +14,12 @@ type ApiResponse<T = any> = {
 };
 /** Promise of an API response, what a handler returns */
 type ApiPromise<T = any> = Promise<ApiResponse<T>>;
-/** Query parameters sent in the `query` header (JSON). */
+/** Query parameters, sent as the JSON body of a `QUERY` request */
 type QueryParams = {
   skip?: number;
   top?: number;
   filter?: NanoObject;
-  orderby?: Record<string, 'asc' | 'desc'>;
+  orderby?: NanoObject<'asc' | 'desc'>;
   select?: string;
 };
 //#endregion
@@ -27,6 +28,8 @@ type QueryParams = {
 type Params<DB = any> = Partial<NanoObject & {
   db?: DB;
   onBeforeResult?: NanoObject;
+  /** `{ user, session }` of Better Auth, on the routes behind its guard */
+  session?: NanoObject;
 }>;
 /** Endpoint handlers */
 type Handler<DB> = (req: Request$1, params: Params<DB>) => ApiPromise;
@@ -116,7 +119,7 @@ type PackagesConfig = {
   /** Morgan configuration */
   morgan?: false | {
     /** Morgan tokens */
-    tokens?: Record<string, any>;
+    tokens?: NanoObject<any>;
     /** Morgan format */
     format: string;
   };
@@ -132,6 +135,8 @@ type PackagesConfig = {
   express?: Partial<Parameters<typeof express.json>[0]> | false;
   /** urlencoded configuration */
   urlencoded?: Partial<Parameters<typeof express.urlencoded>[0]> | false;
+  /** Better Auth options, without `database`: it uses the app's Prisma client. Defaults to false */
+  betterAuth?: Omit<BetterAuthOptions, 'database'> | false;
 };
 /** Application configuration */
 type NanoAppConfig = {
@@ -140,7 +145,7 @@ type NanoAppConfig = {
   /** Application port. Defaults to 3000 */
   port?: number;
   /** Values applied with Express `app.set()` (e.g. `{ "trust proxy": 1 }`) */
-  settings?: Record<string, unknown>;
+  settings?: NanoObject<unknown>;
   /** Default middlewares configuration */
   packages?: PackagesConfig;
   /** Plugins to mount. Defaults to [] */

package/build/index.js

@@ -1,4 +1,4 @@
-import { a as Formatter, i as FileLoader, n as MISSING_DATABASE_URL, o as FileReader, r as OFFICIAL_PLUGINS, t as Prisma } from "./Prisma-Dq-lYuz3.js";
+import { createRequire } from "node:module";
 import express from "express";
 import morgan from "morgan";
 import cors from "cors";
@@ -6,8 +6,159 @@ import helmet from "helmet";
 import compression from "compression";
 import rateLimit from "express-rate-limit";
 import "dotenv/config";
-import { dirname, join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { glob } from "glob";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"DELETE",
+	"QUERY"
+];
+const STORE_TYPES = ["app", "api"];
+/** Checks the consumer's files: invalid ones are warned about and discarded */
+var Validator = class Validator {
+	static oValidators = {
+		route: () => this.isRoute,
+		prisma: () => this.isPrisma,
+		store: () => this.isStore
+	};
+	/** Warns about an invalid file and returns `false`, to discard it */
+	static warn(sFilePath, sMessage) {
+		console.warn(`[nano-app] [WARNING] ${sFilePath}: ${sMessage}`);
+		return false;
+	}
+	/** Checks that the default export is an object */
+	static isObject(oEntry, sFilePath) {
+		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.
+	*/
+	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.");
+		return true;
+	}
+	/** Type guard for a `*.store.ts` entry */
+	static isStore(oEntry, sFilePath) {
+		if (!Validator.isObject(oEntry, sFilePath)) return false;
+		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.");
+		return true;
+	}
+	/**
+	* 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];
+		if (sProvider !== "postgresql") return Validator.warn(sFilePath, `the datasource provider must be "postgresql"${sProvider ? `, not "${sProvider}"` : ""}.`);
+		return true;
+	}
+	/** Validates a full map of entries and returns only the valid ones */
+	static validate(oEntries, sExtension) {
+		const oValid = {};
+		for (const [sFilePath, oEntry] of Object.entries(oEntries)) {
+			const oValidated = this.validateUnique(oEntry, sExtension, sFilePath);
+			if (oValidated !== void 0) oValid[sFilePath] = oValidated;
+		}
+		return oValid;
+	}
+	/** Validates one entry: returns it when valid, `undefined` otherwise */
+	static validateUnique(oEntry, sExtension, sFilePath = "") {
+		return this.oValidators[sExtension]?.()(oEntry, sFilePath) ? oEntry : void 0;
+	}
+};
+//#endregion
+//#region ../core/loader/FileReader.ts
+/** Reads and loads files from disk, resolved from `cwd` */
+var FileReader = class {
+	static oJiti = createJiti(import.meta.url, { nativeModules: ["@prisma/client"] });
+	/** Loads a module via jiti */
+	static async loadModule(sFilePath, oOptions = {}) {
+		return await this.oJiti.import(this.getAbsolutePath(sFilePath), oOptions);
+	}
+	/** Reads the contents of a file */
+	static loadFile(sFilePath) {
+		const sContent = readFileSync(this.getAbsolutePath(sFilePath), "utf-8");
+		if (!sContent) throw new Error(`[nano-app] [ERROR] The file ${sFilePath} does not have valid content.`);
+		return sContent;
+	}
+	/** Reads a Prisma schema without its `//` comments */
+	static loadSchema(sFilePath) {
+		return this.loadFile(sFilePath).replace(/\/\/.*$/gm, "");
+	}
+	/** Resolves the absolute path of a file */
+	static getAbsolutePath(sFilePath) {
+		const sAbsolutePath = isAbsolute(sFilePath) ? sFilePath : resolve(process.cwd(), sFilePath);
+		if (!existsSync(sAbsolutePath)) throw new Error(`[nano-app] [ERROR] ${sFilePath} not found.`);
+		return sAbsolutePath;
+	}
+};
+//#endregion
+//#region ../core/utils/Formatter.ts
+/** Formats values for logs and messages */
+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);
+	}
+	/** Formats a date for the request log, in UTC: `2026-10-19 12:03:10` */
+	static logDate(oDate = /* @__PURE__ */ new Date()) {
+		return oDate.toISOString().slice(0, 19).replace("T", " ");
+	}
+};
+//#endregion
+//#region ../core/loader/FileLoader.ts
+/** Finds, loads and validates the consumer's files */
+var FileLoader = class {
+	/**
+	* 1. Validates a `.prisma` file.
+	* 2. Loads a generated Prisma client module (`client.ts`, or `client.js`)
+	*/
+	static async findPrismaClient(sClientPath, sSchemaPath) {
+		const sContent = FileReader.loadSchema(sSchemaPath);
+		if (!Validator.validateUnique(sContent, "prisma", sSchemaPath)) throw new Error(`[nano-app] [ERROR] ${sSchemaPath} is not a valid Prisma schema.`);
+		try {
+			return (await FileReader.loadModule(sClientPath))?.PrismaClient;
+		} catch (oError) {
+			throw new Error(`[nano-app] [ERROR] The Prisma client ${sClientPath} could not be loaded: ${Formatter.error(oError)}`);
+		}
+	}
+	/** Finds `*.route.ts` (or built `.js`) files and returns `{ [subPath]: defaultExport }` */
+	static async findMany({ extension, sourceDir }) {
+		const sSrcDir = (sourceDir ?? `src/${extension}s`).replace(/^\.\//, "").replace(/\/$/, "");
+		const aFilePaths = await glob(`${sSrcDir}/**/*.${extension}.{ts,js}`, {
+			posix: true,
+			ignore: "**/*.d.ts"
+		});
+		const oEntries = {};
+		for (const sFilePath of aFilePaths) {
+			const sFileSubPath = sFilePath.slice(sSrcDir.length).replace(new RegExp(`\\.${extension}\\.(ts|js)$`), "");
+			const sKey = extension === "store" ? sFileSubPath.slice(1).replaceAll("/", "_") : sFileSubPath;
+			oEntries[sKey] = await FileReader.loadModule(sFilePath, { default: true });
+		}
+		return Validator.validate(oEntries, extension);
+	}
+};
+//#endregion
 //#region src/routes/Endpoint.ts
 /** Base class for all endpoints */
 var Endpoint = class {
@@ -32,8 +183,12 @@ var Endpoint = class {
 				status: 405,
 				message: `Method ${sMethod} not implemented`
 			});
-			(this.oCallbacks.onBefore?.(oReq, sMethod, oParams) ?? Promise.resolve({})).then((onBeforeResult) => fnMethod(oReq, {
+			const oRequestParams = {
 				...oParams,
+				session: oRes.locals.session
+			};
+			(this.oCallbacks.onBefore?.(oReq, sMethod, oRequestParams) ?? Promise.resolve({})).then((onBeforeResult) => fnMethod(oReq, {
+				...oRequestParams,
 				onBeforeResult
 			})).then((oResponse) => {
 				oRes.status(oResponse.success ? 200 : 400).json(oResponse);
@@ -73,6 +228,116 @@ var Router = class {
 	}
 };
 //#endregion
+//#region src/auth/BetterAuth.ts
+/** Better Auth on the app's Prisma client: the instance, its handler and a session guard */
+var BetterAuth = class {
+	/** Creates the instance on the app's client, its handler and the guard */
+	static async create(oOptions, oDb) {
+		const { betterAuth } = await import("better-auth");
+		const { prismaAdapter } = await import("better-auth/adapters/prisma");
+		const { getSchema } = await import("better-auth/db");
+		const { fromNodeHeaders, toNodeHandler } = await import("better-auth/node");
+		const aMissing = Object.keys(getSchema(oOptions)).filter((sModel) => !oDb[sModel]);
+		if (aMissing.length) throw new Error(`[nano-app] [ERROR] Better Auth needs the models ${aMissing.join(", ")} in the app's schema. Run \`npx auth generate\` and apply your schema with Prisma.`);
+		const oAuth = betterAuth({
+			...oOptions,
+			database: prismaAdapter(oDb, { provider: "postgresql" })
+		});
+		const fnGuard = (oReq, oRes, fnNext) => {
+			oAuth.api.getSession({ headers: fromNodeHeaders(oReq.headers) }).then((oSession) => {
+				if (!oSession) return fnNext({
+					status: 401,
+					message: "Not authenticated"
+				});
+				oRes.locals.session = oSession;
+				fnNext();
+			}).catch(fnNext);
+		};
+		return {
+			oHandler: toNodeHandler(oAuth),
+			fnGuard,
+			sPath: `${oOptions.basePath ?? "/api/auth"}/{*path}`
+		};
+	}
+};
+//#endregion
+//#region src/database/Prisma.ts
+/** Runs the consumer's Prisma CLI: generates clients and applies official plugins' migrations */
+var Prisma = class {
+	/** Folder of a client and its files, in the project */
+	static dir(sName) {
+		return join(process.cwd(), ".nano-app", "prisma-clients", sName);
+	}
+	/** Generates the client of a schema in `.nano-app/prisma-clients/<name>`, unless it is up to date */
+	static generate(sName, sSchemaPath) {
+		const sDir = this.dir(sName);
+		const sSource = FileReader.getAbsolutePath(sSchemaPath);
+		const sHash = createHash("sha256").update(readFileSync(sSource)).digest("hex");
+		const sSourceFile = join(sDir, "source.json");
+		const oCurrent = existsSync(sSourceFile) ? JSON.parse(readFileSync(sSourceFile, "utf-8")) : void 0;
+		if (oCurrent && oCurrent.schemaPath !== sSource) console.warn(`[nano-app] [WARNING] .nano-app/prisma-clients/${sName} has the client of ${oCurrent.schemaPath}: it is replaced by the one of ${sSource}.`);
+		if (oCurrent?.schemaPath === sSource && oCurrent.hash === sHash && existsSync(join(sDir, "generated", "client.ts"))) return;
+		mkdirSync(sDir, { recursive: true });
+		const sSchema = readFileSync(sSource, "utf-8");
+		writeFileSync(join(sDir, "schema.prisma"), sSchema.replace(/output\s*=\s*"[^"]*"/, "output = \"./generated\""));
+		this.run(sName, [
+			"generate",
+			"--schema",
+			join(sDir, "schema.prisma")
+		]);
+		writeFileSync(sSourceFile, JSON.stringify({
+			schemaPath: sSource,
+			hash: sHash
+		}));
+		console.log(`[nano-app] [INFO] Prisma client "${sName}" generated`);
+	}
+	/** Applies the pending migrations an official plugin ships next to its schema */
+	static migrate(sName, sSchemaPath, sDbSchema) {
+		const sMigrations = join(dirname(FileReader.getAbsolutePath(sSchemaPath)), "migrations");
+		if (!existsSync(sMigrations)) throw new Error(`[nano-app] [ERROR] The plugin "${sName}" ships no migrations: ${sMigrations}`);
+		if (!process.env.DATABASE_URL) throw new Error(MISSING_DATABASE_URL);
+		const oUrl = new URL(process.env.DATABASE_URL);
+		oUrl.searchParams.set("schema", sDbSchema);
+		const sConfig = join(this.dir(sName), "prisma.config.mjs");
+		writeFileSync(sConfig, [
+			"export default {",
+			`  schema: ${JSON.stringify(join(this.dir(sName), "schema.prisma"))},`,
+			`  migrations: { path: ${JSON.stringify(sMigrations)} },`,
+			"  datasource: { url: process.env.NANO_APP_MIGRATION_URL },",
+			"};",
+			""
+		].join("\n"));
+		this.run(sName, [
+			"migrate",
+			"deploy",
+			"--config",
+			sConfig
+		], { NANO_APP_MIGRATION_URL: oUrl.toString() });
+	}
+	/** Runs a Prisma command of the consumer's `prisma` package */
+	static run(sName, aArgs, oEnv = {}) {
+		let sCli;
+		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.`);
+		}
+		try {
+			execFileSync(process.execPath, [sCli, ...aArgs], {
+				env: {
+					...process.env,
+					...oEnv
+				},
+				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}`);
+		}
+	}
+};
+//#endregion
 //#region src/database/Database.ts
 /** Prisma clients of the app and its plugins, one per name */
 var Database = class {
@@ -138,9 +403,11 @@ var Database = class {
 /** A group of routes, with its options, callbacks and database */
 var Plugin = class {
 	oConfig;
-	/** Creates a new Plugin instance */
-	constructor(oConfig) {
+	oAuthOptions;
+	/** Creates a new Plugin instance; the app's plugin also gets the Better Auth options */
+	constructor(oConfig, oAuthOptions) {
 		this.oConfig = oConfig;
+		this.oAuthOptions = oAuthOptions;
 	}
 	/** Mounts its endpoints on express app */
 	async mount(oApp) {
@@ -150,6 +417,12 @@ var Plugin = class {
 			...options,
 			db: oDb
 		};
+		if (this.oAuthOptions) {
+			if (!oDb) throw new Error("[nano-app] [ERROR] packages.betterAuth needs the database of the app: set mainPlugin.database.enabled to true.");
+			const { sPath, oHandler, fnGuard } = await BetterAuth.create(this.oAuthOptions, oDb);
+			oApp.all(sPath, oHandler);
+			oApp.use(fnGuard);
+		}
 		await callbacks?.onMount?.(oApp, oParams);
 		const oRouter = new Router(routesDir, basePath);
 		for (const { path, endpoint } of await oRouter.mount()) oApp.all(path, await endpoint.mount(oParams));
@@ -186,7 +459,8 @@ const INITIAL_CONFIG = {
 			message: "Too many requests, please try again later."
 		},
 		express: { limit: "10kb" },
-		urlencoded: { extended: false }
+		urlencoded: { extended: false },
+		betterAuth: false
 	},
 	/** Main plugin to mount */
 	mainPlugin: {
@@ -294,7 +568,8 @@ var NanoApp = class {
 		};
 		for (const oPlugin of this.oConfig.plugins) oPlugins[oPlugin.stage ?? "before"].push(oPlugin);
 		for (const oPlugin of oPlugins.before) await new Plugin(oPlugin).mount(this.oApp);
-		await new Plugin(this.oConfig.mainPlugin).mount(this.oApp);
+		const { mainPlugin, packages } = this.oConfig;
+		await new Plugin(mainPlugin, packages.betterAuth).mount(this.oApp);
 		for (const oPlugin of oPlugins.after) await new Plugin(oPlugin).mount(this.oApp);
 		this.oApp.use(notFoundHandler);
 		this.oApp.use(errorHandler);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/backend",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Express server with file-convention routes, plugins and an optional PostgreSQL layer",
   "type": "module",
   "main": "build/index.js",
@@ -18,7 +18,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "test": "tsx --env-file-if-exists=../.env --test tests/*.test.ts",
+    "test": "tsx --env-file-if-exists=../.env --test tests/*.test.ts ../core/tests/*.test.ts",
     "prepublishOnly": "pnpm run build"
   },
   "keywords": [
@@ -56,6 +56,7 @@
   "peerDependencies": {
     "@prisma/adapter-pg": "^7.10.1",
     "@prisma/client": "^7.10.1",
+    "better-auth": "^1.7.12",
     "pg": "^8.23.1"
   },
   "peerDependenciesMeta": {
@@ -65,6 +66,9 @@
     "@prisma/client": {
       "optional": true
     },
+    "better-auth": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }
@@ -78,13 +82,11 @@
     "@types/morgan": "^1.9.10",
     "@types/node": "^26.6.5",
     "@types/pg": "^8.20.0",
+    "better-auth": "^1.7.12",
     "pg": "^8.23.1",
     "prisma": "^7.10.1",
     "tsdown": "^0.23.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
-  },
-  "bin": {
-    "nano-app": "build/nano-app.js"
   }
 }

package/build/Prisma-Dq-lYuz3.js

@@ -1,221 +0,0 @@
-import { createRequire } from "node:module";
-import { glob } from "glob";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createJiti } from "jiti";
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-//#region ../core/loader/Validator.ts
-const HTTP_METHODS = [
-	"GET",
-	"POST",
-	"PUT",
-	"DELETE",
-	"QUERY"
-];
-/** Checks the consumer's files: invalid ones are warned about and discarded */
-var Validator = class Validator {
-	static oValidators = {
-		route: () => this.isRoute,
-		prisma: () => this.isPrisma
-	};
-	/** Warns about an invalid file and returns `false`, to discard it */
-	static warn(sFilePath, sMessage) {
-		console.warn(`[nano-app] [WARNING] ${sFilePath}: ${sMessage}`);
-		return false;
-	}
-	/** Checks that the default export is an object */
-	static isObject(oEntry, sFilePath) {
-		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.
-	*/
-	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.");
-		return true;
-	}
-	/**
-	* 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];
-		if (sProvider !== "postgresql") return Validator.warn(sFilePath, `the datasource provider must be "postgresql"${sProvider ? `, not "${sProvider}"` : ""}.`);
-		return true;
-	}
-	/** Validates a full map of entries and returns only the valid ones */
-	static validate(oEntries, sExtension) {
-		const oValid = {};
-		for (const [sFilePath, oEntry] of Object.entries(oEntries)) {
-			const oValidated = this.validateUnique(oEntry, sExtension, sFilePath);
-			if (oValidated !== void 0) oValid[sFilePath] = oValidated;
-		}
-		return oValid;
-	}
-	/** Validates one entry: returns it when valid, `undefined` otherwise */
-	static validateUnique(oEntry, sExtension, sFilePath = "") {
-		return this.oValidators[sExtension]?.()(oEntry, sFilePath) ? oEntry : void 0;
-	}
-};
-//#endregion
-//#region ../core/loader/FileReader.ts
-/** Reads and loads files from disk, resolved from `cwd` */
-var FileReader = class {
-	static oJiti = createJiti(import.meta.url, { nativeModules: ["@prisma/client"] });
-	/** Loads a module via jiti */
-	static async loadModule(sFilePath, oOptions = {}) {
-		return await this.oJiti.import(this.getAbsolutePath(sFilePath), oOptions);
-	}
-	/** Reads the contents of a file */
-	static loadFile(sFilePath) {
-		const sContent = readFileSync(this.getAbsolutePath(sFilePath), "utf-8");
-		if (!sContent) throw new Error(`[nano-app] [ERROR] The file ${sFilePath} does not have valid content.`);
-		return sContent;
-	}
-	/** Reads a Prisma schema without its `//` comments */
-	static loadSchema(sFilePath) {
-		return this.loadFile(sFilePath).replace(/\/\/.*$/gm, "");
-	}
-	/** Resolves the absolute path of a file */
-	static getAbsolutePath(sFilePath) {
-		const sAbsolutePath = isAbsolute(sFilePath) ? sFilePath : resolve(process.cwd(), sFilePath);
-		if (!existsSync(sAbsolutePath)) throw new Error(`[nano-app] [ERROR] ${sFilePath} not found.`);
-		return sAbsolutePath;
-	}
-};
-//#endregion
-//#region ../core/utils/Formatter.ts
-/** Formats values for logs and messages */
-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);
-	}
-	/** Formats a date for the request log, in UTC: `2026-10-19 12:03:10` */
-	static logDate(oDate = /* @__PURE__ */ new Date()) {
-		return oDate.toISOString().slice(0, 19).replace("T", " ");
-	}
-};
-//#endregion
-//#region ../core/loader/FileLoader.ts
-/** Finds, loads and validates the consumer's files */
-var FileLoader = class {
-	/**
-	* 1. Validates a `.prisma` file.
-	* 2. Loads a generated Prisma client module (`client.ts`, or `client.js`)
-	*/
-	static async findPrismaClient(sClientPath, sSchemaPath) {
-		const sContent = FileReader.loadSchema(sSchemaPath);
-		if (!Validator.validateUnique(sContent, "prisma", sSchemaPath)) throw new Error(`[nano-app] [ERROR] ${sSchemaPath} is not a valid Prisma schema.`);
-		try {
-			return (await FileReader.loadModule(sClientPath))?.PrismaClient;
-		} catch (oError) {
-			throw new Error(`[nano-app] [ERROR] The Prisma client ${sClientPath} could not be loaded: ${Formatter.error(oError)}`);
-		}
-	}
-	/** Finds `*.route.ts` (or built `.js`) files and returns `{ [subPath]: defaultExport }` */
-	static async findMany({ extension, sourceDir }) {
-		const sSrcDir = (sourceDir ?? `src/${extension}s`).replace(/^\.\//, "").replace(/\/$/, "");
-		const aFilePaths = await glob(`${sSrcDir}/**/*.${extension}.{ts,js}`, {
-			posix: true,
-			ignore: "**/*.d.ts"
-		});
-		const oEntries = {};
-		for (const sFilePath of aFilePaths) {
-			const sFileSubPath = sFilePath.slice(sSrcDir.length).replace(new RegExp(`\\.${extension}\\.(ts|js)$`), "");
-			oEntries[sFileSubPath] = await FileReader.loadModule(sFilePath, { default: true });
-		}
-		return Validator.validate(oEntries, extension);
-	}
-};
-//#endregion
-//#region 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 src/database/Prisma.ts
-/** Runs the consumer's Prisma CLI: generates clients and applies official plugins' migrations */
-var Prisma = class {
-	/** Folder of a client and its files, in the project */
-	static dir(sName) {
-		return join(process.cwd(), ".nano-app", "prisma-clients", sName);
-	}
-	/** Generates the client of a schema in `.nano-app/prisma-clients/<name>`, unless it is up to date */
-	static generate(sName, sSchemaPath) {
-		const sDir = this.dir(sName);
-		const sSource = FileReader.getAbsolutePath(sSchemaPath);
-		const sHash = createHash("sha256").update(readFileSync(sSource)).digest("hex");
-		const sSourceFile = join(sDir, "source.json");
-		const oCurrent = existsSync(sSourceFile) ? JSON.parse(readFileSync(sSourceFile, "utf-8")) : void 0;
-		if (oCurrent && oCurrent.schemaPath !== sSource) console.warn(`[nano-app] [WARNING] .nano-app/prisma-clients/${sName} has the client of ${oCurrent.schemaPath}: it is replaced by the one of ${sSource}.`);
-		if (oCurrent?.schemaPath === sSource && oCurrent.hash === sHash && existsSync(join(sDir, "generated", "client.ts"))) return;
-		mkdirSync(sDir, { recursive: true });
-		const sSchema = readFileSync(sSource, "utf-8");
-		writeFileSync(join(sDir, "schema.prisma"), sSchema.replace(/output\s*=\s*"[^"]*"/, "output = \"./generated\""));
-		this.run(sName, [
-			"generate",
-			"--schema",
-			join(sDir, "schema.prisma")
-		]);
-		writeFileSync(sSourceFile, JSON.stringify({
-			schemaPath: sSource,
-			hash: sHash
-		}));
-		console.log(`[nano-app] [INFO] Prisma client "${sName}" generated`);
-	}
-	/** Applies the pending migrations an official plugin ships next to its schema */
-	static migrate(sName, sSchemaPath, sDbSchema) {
-		const sMigrations = join(dirname(FileReader.getAbsolutePath(sSchemaPath)), "migrations");
-		if (!existsSync(sMigrations)) throw new Error(`[nano-app] [ERROR] The plugin "${sName}" ships no migrations: ${sMigrations}`);
-		if (!process.env.DATABASE_URL) throw new Error(MISSING_DATABASE_URL);
-		const oUrl = new URL(process.env.DATABASE_URL);
-		oUrl.searchParams.set("schema", sDbSchema);
-		const sConfig = join(this.dir(sName), "prisma.config.mjs");
-		writeFileSync(sConfig, [
-			"export default {",
-			`  schema: ${JSON.stringify(join(this.dir(sName), "schema.prisma"))},`,
-			`  migrations: { path: ${JSON.stringify(sMigrations)} },`,
-			"  datasource: { url: process.env.NANO_APP_MIGRATION_URL },",
-			"};",
-			""
-		].join("\n"));
-		this.run(sName, [
-			"migrate",
-			"deploy",
-			"--config",
-			sConfig
-		], { NANO_APP_MIGRATION_URL: oUrl.toString() });
-	}
-	/** Runs a Prisma command of the consumer's `prisma` package */
-	static run(sName, aArgs, oEnv = {}) {
-		let sCli;
-		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.`);
-		}
-		try {
-			execFileSync(process.execPath, [sCli, ...aArgs], {
-				env: {
-					...process.env,
-					...oEnv
-				},
-				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}`);
-		}
-	}
-};
-//#endregion
-export { Formatter as a, FileLoader as i, MISSING_DATABASE_URL as n, FileReader as o, OFFICIAL_PLUGINS as r, Prisma as t };

package/build/nano-app.js

@@ -1,46 +0,0 @@
-#!/usr/bin/env node
-import { r as OFFICIAL_PLUGINS, t as Prisma } from "./Prisma-Dq-lYuz3.js";
-import { dirname, join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
-//#region bin/nano-app.ts
-/**
-* Generates a Prisma client where nano-app reads it, as the startup does: for the build or the editor.
-*   nano-app generate                     the app's schema (src/prisma/schema.prisma)
-*   nano-app generate <name>              an official plugin's, from the installed @nano-app/plugins
-*   nano-app generate <name> --schema <path>
-*/
-const [sCommand, ...aArgs] = process.argv.slice(2);
-/** package.json of @nano-app/plugins: the project itself (its tests) or one in a node_modules */
-function officialPackage() {
-	for (let sDir = process.cwd();; sDir = dirname(sDir)) {
-		const sOwn = join(sDir, "package.json");
-		if (existsSync(sOwn) && JSON.parse(readFileSync(sOwn, "utf-8")).name === "@nano-app/plugins") return sOwn;
-		const sInstalled = join(sDir, "node_modules", OFFICIAL_PLUGINS, "package.json");
-		if (existsSync(sInstalled)) return sInstalled;
-		if (dirname(sDir) === sDir) return void 0;
-	}
-}
-/** Schema of an official plugin: next to the entry @nano-app/plugins exports for it */
-function pluginSchema(sName) {
-	const sPackage = officialPackage();
-	if (!sPackage) return `${OFFICIAL_PLUGINS} is not installed`;
-	const oExport = JSON.parse(readFileSync(sPackage, "utf-8")).exports["./*"];
-	const sTarget = oExport.import ?? oExport.default;
-	return join(dirname(sPackage), dirname(sTarget.replaceAll("*", sName)), "schema.prisma");
-}
-try {
-	if (sCommand !== "generate") throw new Error("[nano-app] [ERROR] Usage: nano-app generate [name] [--schema <path>]");
-	const iSchemaFlag = aArgs.indexOf("--schema");
-	const sSchemaFlag = iSchemaFlag >= 0 ? aArgs[iSchemaFlag + 1] : void 0;
-	const fnIsFlagPart = (iIndex) => iSchemaFlag >= 0 && (iIndex === iSchemaFlag || iIndex === iSchemaFlag + 1);
-	const sName = aArgs.find((_sArg, iIndex) => !fnIsFlagPart(iIndex));
-	const sDefault = sName ? pluginSchema(sName) : "src/prisma/schema.prisma";
-	const sSchema = sSchemaFlag ?? sDefault;
-	if (!existsSync(sSchema)) throw new Error(`[nano-app] [ERROR] "${sName ?? "app"}" has no schema: ${sSchema}`);
-	Prisma.generate(sName ?? "app", sSchema);
-} catch (oError) {
-	console.error(oError.message);
-	process.exit(1);
-}
-//#endregion
-export {};