@nano-app/backend 0.7.1 → 0.8.0

package/README.md

@@ -46,17 +46,17 @@ 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` adds parameters:
+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):
 
 ```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" }),
 });
 ```
 
-Each handler receives `(req, db)` — `db` is the Prisma client when a database is enabled ([Database](#database)) — and returns an `ApiResponse`:
+Each handler receives `(req, params)` and returns an `ApiResponse`. `params` holds the plugin's `options`, `db` (the Prisma client when a database is enabled, see [Database](#database)) and `onBeforeResult` (see [Callbacks](#callbacks)):
 
 ```ts
 type ApiResponse<T> = {
@@ -80,7 +80,7 @@ Every option is optional.
 | `listener` | `() => {}` | Callback once the server is listening. |
 | `settings` | `{}` | Values for `app.set()` (e.g. `{ "trust proxy": 1 }`). |
 | `packages` | see below | Framework base middlewares. |
-| `mainPlugin` | `{ routesDir: "src/routes", basePath: "/" }` | Your routes (`routesDir`, relative to `cwd`), `basePath`, `init` and database: see [Database](#database). |
+| `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.
@@ -137,8 +137,8 @@ createNanoApp({ mainPlugin: { database: { enabled: true } } });
 import { createRoute } from "@nano-app/backend";
 import type { PrismaClient } from "../../.nano-app/prisma-clients/app/generated/client";
 
-export default createRoute({
-  GET: async (_req, db: PrismaClient) => ({ success: true, result: await db.user.findMany() }),
+export default createRoute<PrismaClient>({
+  GET: async (_req, { db }) => ({ success: true, result: await db!.user.findMany() }),
 });
 ```
 
@@ -150,12 +150,12 @@ export default createRoute({
 - 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.
-- Annotate `db` with your generated `PrismaClient` to type it; otherwise it is `any`, and without an enabled database `undefined`.
+- 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.
 
 ## Plugins
 
-A plugin is a group of endpoints mounted under a base path. Your routes are mounted as one (named `app`). This package ships no official plugin. 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.
 
 ```ts
 // src/plugins/hello/index.ts
@@ -187,7 +187,32 @@ import hello from "./plugins/hello";
 createNanoApp({ plugins: [hello()] });
 ```
 
-`createPlugin` types the options of that plugin. Each plugin chooses its base path and whether it mounts `before` (default) or `after` your routes.
+`createPlugin` types the options of that plugin. Each plugin chooses its base path and whether it mounts `before` (default) or `after` your routes. What the plugin puts in `options` reaches every callback and handler of its routes in `params`.
+
+### Callbacks
+
+Two levels. Only the plugin's receives the Express app, so nothing app-wide depends on the order of the route files.
+
+| Level | Callback | Runs | Receives | Use |
+|---|---|---|---|---|
+| Plugin (`callbacks` in its config) | `onMount` | Once, after its database and before its endpoints | `(app, params)` | App-level middlewares (a guard), shared setup |
+| Endpoint (`callbacks` in `createRoute`) | `onInit` | Once, when the endpoint is mounted | `(params)` | Setup of that route |
+| Endpoint | `onBefore` | Before every request the endpoint handles | `(req, method, params)` | Validate or load; its return value reaches the handler as `params.onBeforeResult` |
+
+```ts
+export default createPlugin((options?: { publicPaths?: string[] }) => ({
+  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" }));
+    },
+  },
+}));
+```
+
+The endpoints of one plugin have no guaranteed order: one route's `onInit` must not depend on another's. `mainPlugin` takes `callbacks` too.
 
 Everything is mounted on one Express application, in this order: base middlewares → `before` plugins → your routes → `after` plugins → 404 → error handler.
 
@@ -216,8 +241,9 @@ GET /unknown                                        // → 404 { success: false,
 | `createNanoApp(config?)` | Creates and starts the app. |
 | `createRoute(route)` | Types a route file. |
 | `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`).
+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`).
 
 ## Development
 

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import express, { Express, Request } from 'express';
+import express, { Request, Express } from 'express';
 export { Request } from 'express';
 import { Options } from 'express-rate-limit';
 import { CorsOptions } from 'cors';
@@ -11,28 +11,85 @@ type DatabaseConfig = {
     schemaPath: string;
 };
 
+/** API response */
+type ApiResponse<T = any> = {
+    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). */
+type QueryParams = {
+    skip?: number;
+    top?: number;
+    filter?: NanoObject;
+    orderby?: Record<string, "asc" | "desc">;
+    select?: string;
+};
+
+/** Extra params of handlers and callbacks */
+type Params<DB = any> = Partial<NanoObject & {
+    db?: DB;
+    onBeforeResult?: NanoObject;
+}>;
+/** Endpoint handlers */
+type Handler<DB> = (req: Request, params: Params<DB>) => ApiPromise;
+type Handlers<DB = any> = {
+    GET?: Handler<DB>;
+    POST?: Handler<DB>;
+    PUT?: Handler<DB>;
+    DELETE?: Handler<DB>;
+};
+/** Callbacks */
+type Callback<DB> = (params: Params<DB>) => Promise<void>;
+type CallbackMethod<DB> = (req: Request, 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>;
+};
+/** Callbacks of a plugin */
+type PluginCallbacks<DB = any> = {
+    onMount?: CallbackMount<DB>;
+};
+/** Entry of a route file (`*.route.ts`) */
+type RouteEntry<DB = any> = {
+    expression?: string;
+    callbacks?: Callbacks<DB>;
+} & Handlers<DB>;
+type NanoObject<T = any> = Record<string, T>;
+
 /** When a plugin is mounted, relative to the consumer routes */
 type PluginStage = "before" | "after";
 /** Plugin configuration: a group of endpoints */
-type PluginConfig = {
+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 of the plugin. Defaults to "/" */
+    /** 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;
-    /** Callback run first, before the endpoints are mounted */
-    init?: (app: Express, db: any) => void | Promise<void>;
+    /** 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 = {
+type MainPluginConfig<Options = NanoObject> = {
     /** Directory of the project's `*.route.ts` files. Defaults to "src/routes" */
     routesDir?: string;
-    /** Base path prepended to every route. Defaults to "/" */
+    /** Base path prepended to every route, e.g. "/api" (no trailing slash). Defaults to none */
     basePath?: string;
     /** The project's database */
     database?: {
@@ -41,8 +98,10 @@ type MainPluginConfig = {
         /** Prisma schema file, relative to `cwd`. Defaults to "src/prisma/schema.prisma" */
         schemaPath?: string;
     };
-    /** Callback run first, before the routes are mounted */
-    init?: (app: Express, db: any) => void | Promise<void>;
+    /** Plugin options */
+    options?: Options;
+    /** Plugin callbacks */
+    callbacks?: PluginCallbacks;
 };
 
 /** Configuration of the framework's built-in packages */
@@ -83,42 +142,6 @@ type NanoAppConfig = {
     mainPlugin?: MainPluginConfig;
 };
 
-/** API response */
-type ApiResponse<T = any> = {
-    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). */
-type QueryParams = {
-    skip?: number;
-    top?: number;
-    filter?: NanoObject;
-    orderby?: Record<string, "asc" | "desc">;
-    select?: string;
-};
-
-/** Endpoint method: receives the request and, when the plugin has one, its Prisma client */
-type Handler = (req: Request, db?: any) => ApiPromise;
-type Handlers = {
-    GET?: Handler;
-    POST?: Handler;
-    PUT?: Handler;
-    DELETE?: Handler;
-};
-/** Entry of a route file (`*.route.ts`) */
-type RouteEntry = {
-    expression?: string;
-} & Handlers;
-type NanoObject<T = any> = Record<string, T>;
-
 /**
  * Merges the consumer configuration with the initial one.
  */
@@ -141,10 +164,12 @@ declare class NanoApp {
 /** Creates a new NanoApp instance */
 declare function createNanoApp(config?: NanoAppConfig): NanoApp;
 /** Creates and types a route object. */
-declare function createRoute(route: RouteEntry): RouteEntry;
+declare function createRoute<DB>(route: 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;
+type Creator<Options> = (options?: Options) => PluginConfig<Options>;
 declare function createPlugin<Options>(creator: 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, createRoute };
-export type { ApiPromise, ApiResponse, DatabaseConfig, Handler, Handlers, MainPluginConfig, NanoAppConfig, NanoObject, PackagesConfig, PluginConfig, PluginStage, QueryParams, RouteEntry };
+export { NanoApp, createNanoApp, createPlugin, createPluginCallbacks, createRoute };
+export type { ApiPromise, ApiResponse, Callbacks, DatabaseConfig, Handler, Handlers, MainPluginConfig, NanoAppConfig, NanoObject, PackagesConfig, Params, PluginCallbacks, PluginConfig, PluginStage, QueryParams, RouteEntry };

package/build/index.js

@@ -221,17 +221,27 @@ var Formatter = class {
 // src/routes/Endpoint.ts
 var Endpoint = class {
   methods;
+  callbacks;
   /** Allowed methods */
-  constructor(methods) {
+  constructor(methods, callbacks = {}) {
     this.methods = methods;
+    this.callbacks = callbacks;
   }
   /** Handler for all methods */
-  getHandler = (db) => (req, res, next) => {
+  async mount(params) {
+    await this.callbacks.onInit?.(params);
+    return this.createHandler(params);
+  }
+  createHandler = (params) => (req, res, next) => {
     const method = req.method.toUpperCase();
-    if (this.methods[method]) {
-      this.methods[method](req, db).then((response) => {
-        res.status(response.success ? 200 : 400).json(response);
-      }).catch(next);
+    const fnMethod = this.methods[method];
+    if (fnMethod) {
+      (this.callbacks.onBefore?.(req, method, params) ?? Promise.resolve({})).then((onBeforeResult) => (
+        // Runs the method
+        fnMethod(req, { ...params, onBeforeResult }).then((response) => {
+          res.status(response.success ? 200 : 400).json(response);
+        })
+      )).catch(next);
     } else {
       res.status(405).json({ success: false, message: `Method ${method} not implemented` });
     }
@@ -245,7 +255,7 @@ var Router = class {
   basePath;
   constructor(routesDir, basePath) {
     this.routesDir = routesDir;
-    this.basePath = basePath ?? "/";
+    this.basePath = basePath ?? "";
   }
   async mount() {
     if (!!this.routesDir) {
@@ -254,23 +264,15 @@ var Router = class {
         extension: "route"
       });
     }
-    return Object.entries(this.routes).map(([filePath, { expression, ...methods }]) => {
+    return Object.entries(this.routes).map(([filePath, { expression, callbacks, ...methods }]) => {
       const path = this.createPath(filePath, expression);
       console.log(`[nano-app] [INFO] ${path}`);
-      return { path, endpoint: new Endpoint(methods) };
+      return { path, endpoint: new Endpoint(methods, callbacks) };
     });
   }
-  createPath(endpoint, expression) {
-    const isIndex = endpoint === "/index";
-    let path = isIndex ? "/" : endpoint;
-    if (!!expression) {
-      path = `${isIndex ? "" : endpoint.replace(/\/+$/, "")}/${expression.replace(/^\/+/, "")}`;
-    }
-    const basePath = this.basePath.replace(/\/+$/, "");
-    if (basePath) {
-      path = path === "/" ? basePath : `${basePath}${path}`;
-    }
-    return path;
+  /** `basePath` + file path (`/index` is the folder itself) + `expression`, as Express reads them */
+  createPath(endpoint, expression = "") {
+    return `${this.basePath}${endpoint.replace(/\/index$/, "")}${expression}` || "/";
   }
 };
 
@@ -346,11 +348,12 @@ var Plugin = class {
   }
   /** Mounts its endpoints on express app */
   async mount(app) {
-    const { name, routesDir, basePath, database, init } = this.config;
+    const { name, routesDir, basePath, database, options, callbacks } = this.config;
     const router = new Router(routesDir, basePath);
     const db = database?.enabled ? await Database.mount(name, database) : void 0;
-    await init?.(app, db);
-    for (const { path, endpoint } of await router.mount()) app.all(path, endpoint.getHandler(db));
+    const params = { ...options, db };
+    await callbacks?.onMount?.(app, params);
+    for (const { path, endpoint } of await router.mount()) app.all(path, await endpoint.mount(params));
   }
 };
 
@@ -396,7 +399,7 @@ var INITIAL_CONFIG = {
   /** Main plugin to mount */
   mainPlugin: {
     routesDir: "src/routes",
-    basePath: "/",
+    basePath: "",
     database: {
       enabled: false,
       schemaPath: "src/prisma/schema.prisma"
@@ -536,9 +539,13 @@ function createRoute(route) {
 function createPlugin(creator) {
   return creator;
 }
+function createPluginCallbacks(callbacks) {
+  return callbacks;
+}
 export {
   NanoApp,
   createNanoApp,
   createPlugin,
+  createPluginCallbacks,
   createRoute
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/backend",
-  "version": "0.7.1",
+  "version": "0.8.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": "tsup",
     "dev": "tsup --watch",
-    "test": "tsx --test tests/*.test.ts",
+    "test": "tsx --env-file-if-exists=../.env --test tests/*.test.ts",
     "prepublishOnly": "pnpm run build"
   },
   "keywords": [