@nano-app/backend 0.8.3 → 0.10.0

package/README.md

@@ -1,5 +1,7 @@
 # @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.
@@ -46,7 +48,7 @@ export default createRoute({
 
 ## Routes
 
-Each `*.route.ts` under `mainPlugin.routesDir` default-exports an object with the HTTP methods it implements. **The file path is the URL** (`index.route.ts` → `/`, `api/users.route.ts` → `/api/users`). `expression` is appended to that path as is, in Express syntax (`/:id`, `{/:id}` for optional):
+Each `*.route.ts` under `mainPlugin.routesDir` default-exports an object with the HTTP methods it implements (`GET`, `POST`, `PUT`, `DELETE`, `QUERY`). **The file path is the URL** (`index.route.ts` → `/`, `api/users.route.ts` → `/api/users`). `expression` is appended to that path as is, in Express syntax (`/:id`, `{/:id}` for optional):
 
 ```ts
 export default createRoute({
@@ -83,7 +85,7 @@ 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({
@@ -98,11 +100,10 @@ createNanoApp({
 
 ## Database
 
-Off until enabled: it loads the Prisma client you generated and passes it to your handlers as their second parameter. **It never modifies your database**: generating the client and migrating are up to you, with the Prisma CLI.
+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/client @prisma/adapter-pg pg
-npm install -D prisma
+npm install prisma @prisma/client @prisma/adapter-pg pg   # prisma too: the startup generates the client
 ```
 
 ```prisma
@@ -113,7 +114,7 @@ datasource db {
 
 generator client {
   provider = "prisma-client"
-  output   = "./client"
+  output   = "./client"   // any value: nano-app generates in .nano-app/prisma-clients/app
 }
 
 model User {
@@ -122,11 +123,6 @@ model User {
 }
 ```
 
-```bash
-npx nano-app generate              # client in .nano-app/prisma-clients/app (add .nano-app/ to .gitignore)
-npx nano-app push                  # generate + prisma db push; or any Prisma command: npx nano-app migrate dev …
-```
-
 ```ts
 // src/app.ts — DATABASE_URL comes from the environment (or a .env file)
 createNanoApp({ mainPlugin: { database: { enabled: true } } });
@@ -144,18 +140,66 @@ export default createRoute<PrismaClient>({
 
 | Option | Default | Description |
 |---|---|---|
-| `mainPlugin.database.enabled` | `false` | Mounts your client at startup. |
-| `mainPlugin.database.schemaPath` | `"src/prisma/schema.prisma"` | The single `.prisma` file the client was generated from; its datasource must be `postgresql`. |
-
-- Each key falls back to its default, so `{ enabled: true }` is enough with the default layout. The client is always read from `.nano-app/prisma-clients/app/`, where `nano-app generate` writes it.
-- Startup fails if `DATABASE_URL` is missing or the client cannot be loaded or is not a valid PostgreSQL Prisma client. The connection opens on the first query.
-- The `nano_` prefix is reserved for the framework's plugins: a datasource schema starting with it fails the startup.
+| `mainPlugin.database.enabled` | `false` | Generates and mounts your client at startup. |
+| `mainPlugin.database.schemaPath` | `"src/prisma/schema.prisma"` | Your single `.prisma` file; its datasource must be `postgresql`. |
+
+- 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.
+- 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
+npm install 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.
+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
@@ -216,12 +260,7 @@ 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 its own Prisma schema is generated by name. `nano-app generate <name>` reads `plugins/<name>/schema.prisma` from this package when the plugin ships inside it. A plugin you keep in your app points `database.schemaPath` at your own file and you generate that client yourself. See [PLUGINS.md](https://github.com/Nano-Nathan/nano-app/blob/main/PLUGINS.md).
-
-```bash
-npx nano-app generate            # the app schema (src/prisma/schema.prisma) → .nano-app/prisma-clients/app
-npx nano-app push                # generate + prisma db push
-```
+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).
 
 ## Errors
 
@@ -248,8 +287,8 @@ Also exported: the configuration types (`NanoAppConfig`, `PackagesConfig`, `Plug
 ## Development
 
 ```bash
-pnpm build     # tsup → build/ (ESM + .d.ts)
-pnpm dev       # tsup --watch
+pnpm build     # tsdown → build/ (ESM + .d.ts)
+pnpm dev       # tsdown --watch
 pnpm test      # node:test against the real server (tsx --test)
 DATABASE_URL=postgres://… pnpm test   # also runs the PostgreSQL suite
 ```

package/build/index.d.ts

@@ -1,175 +1,188 @@
-import express, { Request, Express } from 'express';
-export { Request } from 'express';
-import { Options } from 'express-rate-limit';
-import { CorsOptions } from 'cors';
-
-/** Database client configuration. */
-type DatabaseConfig = {
-    /** Whether the database is enabled. Defaults to false */
-    enabled?: boolean;
-    /** Prisma schema file (`.prisma`), relative to `cwd` */
-    schemaPath: string;
-};
-
+import express, { Express, Request, Request as Request$1 } from "express";
+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> = {
-    success?: boolean;
-    result?: T;
-    message?: string;
-    warning?: boolean;
+  success?: boolean;
+  result?: T;
+  message?: string;
+  warning?: boolean;
 };
-type ApiPromise<T = any> = Promise<{
-    success?: boolean;
-    result?: T;
-    message?: string;
-    warning?: boolean;
-}>;
-/** Query parameters sent in the `query` header (JSON). */
+/** Promise of an API response, what a handler returns */
+type ApiPromise<T = any> = Promise<ApiResponse<T>>;
+/** Query parameters, sent as the JSON body of a `QUERY` request */
 type QueryParams = {
-    skip?: number;
-    top?: number;
-    filter?: NanoObject;
-    orderby?: Record<string, "asc" | "desc">;
-    select?: string;
+  skip?: number;
+  top?: number;
+  filter?: NanoObject;
+  orderby?: NanoObject<'asc' | 'desc'>;
+  select?: string;
 };
-
+//#endregion
+//#region ../core/types/objects.d.ts
 /** Extra params of handlers and callbacks */
 type Params<DB = any> = Partial<NanoObject & {
-    db?: DB;
-    onBeforeResult?: 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, params: Params<DB>) => ApiPromise;
+type Handler<DB> = (req: Request$1, params: Params<DB>) => ApiPromise;
 type Handlers<DB = any> = {
-    GET?: Handler<DB>;
-    POST?: Handler<DB>;
-    PUT?: Handler<DB>;
-    DELETE?: Handler<DB>;
+  GET?: Handler<DB>;
+  POST?: Handler<DB>;
+  PUT?: Handler<DB>;
+  DELETE?: Handler<DB>;
+  QUERY?: Handler<DB>;
 };
 /** Callbacks */
 type Callback<DB> = (params: Params<DB>) => Promise<void>;
-type CallbackMethod<DB> = (req: Request, method: string, params: Params<DB>) => Promise<NanoObject>;
+type CallbackMethod<DB> = (req: Request$1, method: string, params: Params<DB>) => Promise<NanoObject>;
 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> = {
-    onInit?: Callback<DB>;
-    onBefore?: CallbackMethod<DB>;
+  /** Run once, when the endpoint is mounted */
+  onInit?: Callback<DB>;
+  /** Run before the endpoint is executed */
+  onBefore?: CallbackMethod<DB>;
 };
 /** Callbacks of a plugin */
 type PluginCallbacks<DB = any> = {
-    onMount?: CallbackMount<DB>;
+  /** Run once with the Express app, after its database and before its endpoints (e.g. app-level middlewares) */
+  onMount?: CallbackMount<DB>;
 };
 /** Entry of a route file (`*.route.ts`) */
 type RouteEntry<DB = any> = {
-    expression?: string;
-    callbacks?: Callbacks<DB>;
+  /** Express route expression appended to the path (e.g. `/:id`) */
+  expression?: string;
+  callbacks?: Callbacks<DB>;
 } & Handlers<DB>;
+/** Generic object */
 type NanoObject<T = any> = Record<string, T>;
-
+//#endregion
+//#region src/types/database.d.ts
+/** Database client configuration. */
+type DatabaseConfig = {
+  /** Whether the database is enabled. Defaults to false */
+  enabled?: boolean;
+  /** Prisma schema file (`.prisma`), relative to `cwd` */
+  schemaPath: string;
+};
+//#endregion
+//#region src/types/plugin.d.ts
 /** When a plugin is mounted, relative to the consumer routes */
-type PluginStage = "before" | "after";
+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: string;
-    /** Directory used to discover the `*.route.ts` files */
-    routesDir: string;
-    /** Base path prepended to every endpoint, e.g. "/auth" (no trailing slash). Defaults to none */
-    basePath?: string;
-    /** Mount point relative to the consumer routes. Defaults to "before" */
-    stage?: PluginStage;
-    /** Prisma client the plugin needs, mounted before its endpoints */
-    database?: DatabaseConfig;
-    /** Plugin options */
-    options?: Options;
-    /** Plugin callbacks */
-    callbacks?: PluginCallbacks;
+  /** Name of the plugin, same as his database (If have one) */
+  name: string;
+  /** Directory used to discover the `*.route.ts` files */
+  routesDir: string;
+  /** Base path prepended to every endpoint, e.g. "/auth" (no trailing slash). Defaults to none */
+  basePath?: string;
+  /** Mount point relative to the consumer routes. Defaults to "before" */
+  stage?: PluginStage;
+  /** Prisma client the plugin needs, mounted before its endpoints */
+  database?: DatabaseConfig;
+  /** Plugin options */
+  options?: Options;
+  /** Plugin callbacks */
+  callbacks?: PluginCallbacks;
 };
 /** The project's plugin: nano-app names it "app" and mounts it between the "before" and "after" plugins */
 type MainPluginConfig<Options = NanoObject> = {
-    /** Directory of the project's `*.route.ts` files. Defaults to "src/routes" */
-    routesDir?: string;
-    /** Base path prepended to every route, e.g. "/api" (no trailing slash). Defaults to none */
-    basePath?: string;
-    /** The project's database */
-    database?: {
-        /** Whether the database is enabled. Defaults to false */
-        enabled?: boolean;
-        /** Prisma schema file, relative to `cwd`. Defaults to "src/prisma/schema.prisma" */
-        schemaPath?: string;
-    };
-    /** Plugin options */
-    options?: Options;
-    /** Plugin callbacks */
-    callbacks?: PluginCallbacks;
+  /** Directory of the project's `*.route.ts` files. Defaults to "src/routes" */
+  routesDir?: string;
+  /** Base path prepended to every route, e.g. "/api" (no trailing slash). Defaults to none */
+  basePath?: string;
+  /** The project's database */
+  database?: {
+    /** Whether the database is enabled. Defaults to false */
+    enabled?: boolean;
+    /** Prisma schema file, relative to `cwd`. Defaults to "src/prisma/schema.prisma" */
+    schemaPath?: string;
+  };
+  /** Plugin options */
+  options?: Options;
+  /** Plugin callbacks */
+  callbacks?: PluginCallbacks;
 };
-
+//#endregion
+//#region src/types/app.d.ts
 /** Configuration of the framework's built-in packages */
 type PackagesConfig = {
-    /** Morgan configuration */
-    morgan?: {
-        /** Morgan tokens */
-        tokens?: Record<string, any>;
-        /** Morgan format */
-        format: string;
-    };
-    /** CORS configuration */
-    cors?: CorsOptions;
-    /** Helmet configuration */
-    helmet?: boolean;
-    /** Compression configuration */
-    compression?: boolean;
-    /** Rate-limit configuration */
-    rateLimit?: Partial<Options>;
-    /** express.json configuration */
-    express?: Partial<Parameters<typeof express.json>[0]>;
-    /** urlencoded configuration */
-    urlencoded?: Partial<Parameters<typeof express.urlencoded>[0]>;
+  /** Morgan configuration */
+  morgan?: false | {
+    /** Morgan tokens */
+    tokens?: NanoObject<any>;
+    /** Morgan format */
+    format: string;
+  };
+  /** CORS configuration */
+  cors?: CorsOptions | false;
+  /** Helmet configuration */
+  helmet?: boolean;
+  /** Compression configuration */
+  compression?: boolean;
+  /** Rate-limit configuration */
+  rateLimit?: Partial<Options> | false;
+  /** express.json configuration */
+  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 = {
-    /** Listener run once the server is listening */
-    listener?: () => void;
-    /** Application port. Defaults to 3000 */
-    port?: number;
-    /** Values applied with Express `app.set()` (e.g. `{ "trust proxy": 1 }`) */
-    settings?: Record<string, unknown>;
-    /** Default middlewares configuration */
-    packages?: PackagesConfig;
-    /** Plugins to mount. Defaults to [] */
-    plugins?: PluginConfig[];
-    /** Main plugin to mount. */
-    mainPlugin?: MainPluginConfig;
+  /** Listener run once the server is listening */
+  listener?: () => void;
+  /** Application port. Defaults to 3000 */
+  port?: number;
+  /** Values applied with Express `app.set()` (e.g. `{ "trust proxy": 1 }`) */
+  settings?: NanoObject<unknown>;
+  /** Default middlewares configuration */
+  packages?: PackagesConfig;
+  /** Plugins to mount. Defaults to [] */
+  plugins?: PluginConfig[];
+  /** Main plugin to mount. */
+  mainPlugin?: MainPluginConfig;
 };
-
-/**
- * Merges the consumer configuration with the initial one.
- */
-declare function mergeConfig(config?: NanoAppConfig): NanoAppConfig & {
-    mainPlugin: PluginConfig;
+//#endregion
+//#region src/app/config.d.ts
+/** Merges the consumer configuration over the initial one; the main plugin is always named "app" */
+declare function mergeConfig(oConfig?: NanoAppConfig): NanoAppConfig & Required<Pick<NanoAppConfig, 'settings' | 'plugins' | 'packages'>> & {
+  mainPlugin: PluginConfig;
 };
-
+//#endregion
+//#region src/app/NanoApp.d.ts
 /** Main NanoApp class */
 declare class NanoApp {
-    protected app: Express;
-    protected config: ReturnType<typeof mergeConfig>;
-    constructor(config?: NanoAppConfig);
-    /** Starts the application */
-    private start;
-    /** Initializes the application in the right order */
-    private initialize;
-    private setPackages;
+  protected oApp: Express;
+  protected oConfig: ReturnType<typeof mergeConfig>;
+  constructor(oConfig?: NanoAppConfig);
+  /** Starts the application */
+  private start;
+  /** Initializes the application in the right order */
+  private initialize;
+  /** Adds the packages according to the configuration */
+  private setPackages;
 }
-
+//#endregion
+//#region src/app/creators.d.ts
 /** Creates a new NanoApp instance */
-declare function createNanoApp(config?: NanoAppConfig): NanoApp;
+export declare function createNanoApp(oConfig?: NanoAppConfig): NanoApp;
 /** Creates and types a route object. */
-declare function createRoute<DB>(route: RouteEntry<DB>): RouteEntry<DB>;
+export declare function createRoute<DB>(oRoute: RouteEntry<DB>): RouteEntry<DB>;
 /** Creates a plugin: a function of the plugin's own options that returns its configuration. */
 type Creator<Options> = (options?: Options) => PluginConfig<Options>;
-declare function createPlugin<Options>(creator: Creator<Options>): Creator<Options>;
+export declare function createPlugin<Options>(fnCreator: Creator<Options>): Creator<Options>;
 /** Creates and types the callbacks of a plugin. */
-declare function createPluginCallbacks<DB>(callbacks: PluginCallbacks<DB>): PluginCallbacks<DB>;
-
-export { NanoApp, createNanoApp, createPlugin, createPluginCallbacks, createRoute };
-export type { ApiPromise, ApiResponse, Callbacks, DatabaseConfig, Handler, Handlers, MainPluginConfig, NanoAppConfig, NanoObject, PackagesConfig, Params, PluginCallbacks, PluginConfig, PluginStage, QueryParams, RouteEntry };
+export declare function createPluginCallbacks<DB>(oCallbacks: PluginCallbacks<DB>): PluginCallbacks<DB>;
+//#endregion
+export { type ApiPromise, type ApiResponse, type Callbacks, type DatabaseConfig, type Handler, type Handlers, type MainPluginConfig, NanoApp, type NanoAppConfig, type NanoObject, type PackagesConfig, type Params, type PluginCallbacks, type PluginConfig, type PluginStage, type QueryParams, type Request, type RouteEntry };