@nano-app/plugins 0.10.0 → 0.12.0

package/README.md

@@ -12,18 +12,19 @@ pnpm add @nano-app/backend @nano-app/plugins
 import { createNanoApp } from '@nano-app/backend';
 import health from '@nano-app/plugins/health';
 
-createNanoApp({ plugins: [health()] });
+createNanoApp({ plugins: { before: [health()] } });
 ```
 
 ## Official plugins
 
 | Plugin   | Import                                          | Endpoints                                                                                                                                                                                                                                 | Options                          |
 | -------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| `health` | `import health from '@nano-app/plugins/health'` | `GET /health` → `{ success: true, result: { status: "ok" } }`                                                                                                                                                                             | `basePath` (default `"/health"`) |
-| `crud`   | `import crud from '@nano-app/plugins/crud'`     | On the tables listed in `models`, by their name in the app's schema (any other answers 404): `GET` and `QUERY` on `/api/<model>{/<id>}` → a list `{ result }` or one record, with `QueryParams` as the body of `QUERY`: Drizzle's relational query (`where`, `columns`, `orderBy`, `limit`, `offset`, `with`); `POST /api/<model>`, `PUT` and `DELETE` on `/api/<model>/<id>` → the record created, updated or deleted. Postgres casts `<id>` to the type of the `id` column. With Better Auth, each method asks for a permission on the table: `read` (`GET`, `QUERY`), `create`, `update`, `delete`, see [crud and related tables](#crud-and-related-tables) | `models` (the published ones), `dbSchema` (the app's Drizzle schema, as in `mainPlugin.database`), `validations` (zod schemas of the bodies, see [crud and the bodies](#crud-and-the-bodies)), `basePath` (default `"/api"`)    |
-| `rate-limit` | `import rateLimit from '@nano-app/plugins/rate-limit'` | None: limits every request of the routes and plugins mounted after it, per client IP (see [Client IP](../backend/README.md#client-ip)); the addresses of an IPv6 `/56` network are one client. Each request spends a token of the client's bucket, which holds `capacity` and refills `refillPerSecond` tokens per second; without one it answers `429` with `message` and `Retry-After` (seconds until the next token). List it first in `plugins`. The buckets live in the memory of each process | `capacity` (default `100`), `refillPerSecond` (default `1`), `message` |
+| `health` | `import health from '@nano-app/plugins/health'` | `GET /health` → `{ success: true, result: { status: "ok" } }`. Public: it answers without a session                                                                                                                                                                             | `basePath` (default `"/health"`) |
+| `crud`   | `import crud from '@nano-app/plugins/crud'`     | One route per table of `models`, keyed by its name in the app's relations (any other answers 404): `GET` and `QUERY` on `/<model>{/<id>}` → a list `{ result }` or one record, with `QueryParams` as the body of `QUERY`: Drizzle's relational query (`where`, `columns`, `orderBy`, `limit`, `offset`, `with`); `POST /<model>`, `PUT` and `DELETE` on `/<model>/<id>` → the record created, updated or deleted. Postgres casts `<id>` to the type of the `id` column. With Better Auth, each method asks for a permission on the table, 403 without it: `read` (`GET`, `QUERY`), `create`, `update`, `delete`, see [crud and related tables](#crud-and-related-tables) | `models` (the published tables, `{ note, comment }`), `validations` (zod schemas of the bodies, see [crud and the bodies](#crud-and-the-bodies)), `basePath` (default none: `/<model>`)    |
 
-What is not CRUD, such as creating a record with business logic, goes in a route of your own with its own URL: a route of yours on a `crud` URL takes every method of it.
+Every plugin takes `basePath` besides its own options, over its default: `crud({ models, basePath: '/api' })` answers on `/api/<model>`.
+
+What is not CRUD, such as creating a record with business logic, goes in a route of your own with its own URL. A `crud` mounted `before` your routes takes its URLs from them; mounted `after`, a route of yours on one of its URLs takes every method of it.
 
 ### crud and the bodies
 
@@ -35,8 +36,7 @@ import { z } from 'zod';
 import * as schema from './db/schema';
 
 crud({
-  models: ['note'],
-  dbSchema: schema,
+  models: { note: schema.note },
   validations: {
     note: {
       create: createInsertSchema(schema.note).omit({ id: true }),
@@ -49,7 +49,7 @@ crud({
 
 ### crud and related tables
 
-A `crud` query runs on the app's client, so it reaches the related tables Drizzle's relations give: `with` loads them and `where` filters by them, also the ones that are not in `models`. With Better Auth, the permission asked is only the one of the URL's table. What a query may load is up to the app: the `read` validation of the model decides it (a `z.strictObject` without `with` keeps a query in its table). Better Auth's tables (`user`, `account` with its password hashes, `session` with its tokens) hold secrets: never publish `account`, `session` or `verification`, and do not relate them to a published table without a `read` validation that leaves them out.
+A `crud` query runs on the app's client, so it reaches the related tables Drizzle's relations give: `with` loads them and `where` filters by them, also the ones that are not in `models`. With Better Auth, the permission asked is only the one of the URL's table. What a query may load is up to the app: the `read` validation of the model decides it (a `z.strictObject` without `with` keeps a query in its table). Better Auth's tables live in `nano_auth`, outside the app's relations: `crud` does not reach them. A Postgres error of a write (a duplicate, a missing reference) answers 500.
 
 ### Layout
 
@@ -58,7 +58,7 @@ plugins/
 └── <name>/
     ├── index.ts        default-exports the plugin factory: the import path
     ├── schema.ts       its tables, when it has any, in the Postgres schema nano_<name>
-    └── routes/         *.route.ts, mounted under the plugin's basePath
+    └── routes/         *.route.ts, when its routes are files, under the plugin's basePath
 ```
 
 ## Write a plugin
@@ -83,10 +83,9 @@ import { createPlugin } from '@nano-app/backend';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export default createPlugin((options?: { basePath?: string }) => ({
+export default createPlugin(() => ({
   name: 'hello',
-  basePath: options?.basePath ?? '/hello',
-  stage: 'before',
+  basePath: '/hello',
   routesDir: resolve(dirname(fileURLToPath(import.meta.url)), 'routes'),
 }));
 ```
@@ -105,14 +104,14 @@ export default createRoute({
 import { createNanoApp } from '@nano-app/backend';
 import hello from './plugins/hello';
 
-createNanoApp({ plugins: [hello()] });
+createNanoApp({ plugins: { before: [hello()] } });
 ```
 
-`stage` is `"before"` (default) or `"after"` the app's own routes. Mount order: base middlewares, `before` plugins, your routes, `after` plugins, 404, error handler.
+The app lists it in `plugins.before` or `plugins.after` its own routes, and moves it with `hello({ basePath: '/hi' })`: `createPlugin` adds `basePath` to the options of every plugin. Mount order: base middlewares, Better Auth, `before` plugins, your routes, `after` plugins, 404, error handler. With Better Auth on, its routes need a session unless they are `public`.
 
-Set `options` in the returned config to pass values to the plugin's routes: every handler and callback receives them in `params`, next to `db`. Callbacks: `callbacks.onMount(app, params)` on the plugin, once, before its endpoints (app-level middlewares go here); `onInit(params)` and `onBefore(req, method, params)` on each route. See the [backend README](../backend/README.md#callbacks).
+Set `options` in the returned config to pass values to the plugin's routes: every handler and callback receives them in `params`, next to `db`. Callbacks: `callbacks.onMount(params)` on the plugin, once, before its endpoints, for its setup; `onInit(params)` and `onBefore(req, method, params)` on each route. See the [backend README](../backend/README.md#callbacks).
 
-`routesDir` must be a real directory of `*.route.ts` files when you run the app from source (`tsx`). `jiti` loads them. There is no compile step for your routes.
+`routesDir` must be a real directory of `*.route.ts` files when you run the app from source (`tsx`). `jiti` loads them. There is no compile step for your routes. A plugin can also pass its routes made in code in `routes`, by path (`{ '/index': createRoute({...}) }`), beside or instead of `routesDir`: they are checked as the files.
 
 ### A plugin other people can install
 
@@ -129,15 +128,15 @@ Publish a separate package. Do not add it to this repository unless a maintainer
 }
 ```
 
-Export the `createPlugin` factory as the package entry. The consumer installs both packages and passes the factory to `plugins`.
+Export the `createPlugin` factory as the package entry. The consumer installs both packages and lists it in `plugins.before` or `plugins.after`.
 
 Use MIT or Apache-2.0 if you want the plugin listed from this repo later. Open an issue with the package name and a short description. A maintainer adds the link. The plugin stays in your repository.
 
 ### Database
 
-Optional. Pass `database: { schema }` on the plugin config: the module of its Drizzle tables, with its `relations` when it has them. Its tables live in the Postgres schema `nano_<plugin name>`, which drizzle-kit creates when the module exports its `pgSchema`; a table elsewhere fails the startup.
+Optional. Pass `database: { relations }` on the plugin config: what `defineRelations` gives of its Drizzle tables. Keep its tables in the Postgres schema `nano_<plugin name>`, reserved for it, which drizzle-kit creates when the module exports its `pgSchema`; a table in the `nano_*` schema of another fails the startup.
 
-Its tables are applied with drizzle-kit by whoever installs it, like the app's schema. Handlers and callbacks receive its client as `params.db`.
+`push: true` applies them at startup, and `migrate` the folder the plugin ships, with its record in `nano_<plugin name>`; without them whoever installs it applies them with drizzle-kit. Handlers and callbacks receive its client as `params.db`.
 
 ### What belongs in this repository
 

package/build/const.js

@@ -0,0 +1,10 @@
+// const.ts
+/** Action of each method: its permission of Better Auth and the validation of its body */
+const ACTIONS = {
+	GET: "read",
+	QUERY: "read",
+	POST: "create",
+	PUT: "update",
+	DELETE: "delete"
+};
+export { ACTIONS };

package/build/core/files/FileLoader.d.ts

@@ -0,0 +1 @@
+import "zod";

package/build/core/index.d.ts

@@ -0,0 +1,4 @@
+import { NanoObject } from "./types/objects.js";
+import "./files/FileLoader.js";
+import "./utils/Validator.js";
+export { NanoObject };

package/build/core/types/objects.d.ts

@@ -0,0 +1,2 @@
+/** Generic object */
+export type NanoObject<T = any> = Record<string, T>;

package/build/core/utils/Validator.d.ts

@@ -0,0 +1 @@
+import "zod";

package/build/crud/index.d.ts

@@ -1,15 +1,11 @@
 import { CrudValidations } from "../types/crud.js";
 import { NanoObject } from "@nano-app/backend";
-/** Automatic CRUD: the listed tables of the app's database on `/api/<model>{/<id>}` */
-declare const _default: (options?: {
-  basePath?: string;
-  models: string[];
-  dbSchema: NanoObject;
+/** Automatic CRUD: the tables of `models` of the app's database on `/<model>{/<id>}` */
+declare const _default: (options?: ({
+  models: NanoObject;
   validations?: NanoObject<CrudValidations>;
-} | undefined) => import("@nano-app/backend").PluginConfig<{
-  basePath?: string;
-  models: string[];
-  dbSchema: NanoObject;
+} & import("@nano-app/backend").PluginOptions) | undefined) => import("@nano-app/backend").PluginConfig<{
+  models: NanoObject;
   validations?: NanoObject<CrudValidations>;
 }>;
 export { _default as default };

package/build/crud/index.js

@@ -1,12 +1,9 @@
+import route from "./route.js";
 import { createPlugin } from "@nano-app/backend";
-import { join } from "node:path";
 // crud/index.ts
-/** Automatic CRUD: the listed tables of the app's database on `/api/<model>{/<id>}` */
+/** Automatic CRUD: the tables of `models` of the app's database on `/<model>{/<id>}` */
 var crud_default = createPlugin((options) => ({
 	name: "crud",
-	basePath: options?.basePath ?? "/api",
-	stage: "after",
-	routesDir: join(import.meta.dirname, "routes"),
-	options
+	routes: Object.fromEntries(Object.entries(options?.models ?? {}).map(([sModel, oTable]) => [`/${sModel}`, route(sModel, oTable, options?.validations?.[sModel])]))
 }));
 export { crud_default as default };

package/build/crud/route.js

@@ -0,0 +1,81 @@
+import { ACTIONS } from "../const.js";
+import { NanoError, createRoute } from "@nano-app/backend";
+import { eq } from "drizzle-orm";
+// crud/route.ts
+/** The first record of a query or a write: 404 without it */
+function first(aRecords) {
+	if (!aRecords[0]) throw new NanoError("Not found", 404);
+	return { result: aRecords[0] };
+}
+/** Every record of a query */
+function list(aRecords) {
+	return { result: aRecords };
+}
+/** A list of the table, or one record by its id, with Drizzle's relational query of the body */
+async function read(_oReq, { db, onBeforeResult }) {
+	const { model, page, answer, body } = onBeforeResult;
+	return answer(await db.query[model].findMany({
+		limit: 100,
+		...body,
+		...page
+	}));
+}
+/** Inserts the body as a record */
+async function create(_oReq, { db, onBeforeResult }) {
+	const { table, body } = onBeforeResult;
+	return first(await db.insert(table).values(body).returning());
+}
+/** Updates the record of the id with the body */
+async function update(_oReq, { db, onBeforeResult }) {
+	const { table, id, body } = onBeforeResult;
+	return first(await db.update(table).set(body).where(eq(table.id, id)).returning());
+}
+/** Deletes the record of the id */
+async function remove(_oReq, { db, onBeforeResult }) {
+	const { table, id } = onBeforeResult;
+	return first(await db.delete(table).where(eq(table.id, id)).returning());
+}
+/** The route of a table: `GET` and `QUERY` read, each method asks its permission on the table */
+function route(sModel, oTable, oValidations = {}) {
+	const oMethods = Object.fromEntries(Object.entries({
+		GET: read,
+		QUERY: read,
+		POST: create,
+		PUT: update,
+		DELETE: remove
+	}).map(([sMethod, handler]) => [sMethod, {
+		handler,
+		permissions: { [sModel]: [ACTIONS[sMethod]] }
+	}]));
+	return createRoute({
+		expression: "{/:id}",
+		callbacks: { onBefore: async (oReq, sMethod) => {
+			const { id } = oReq.params;
+			const oBody = oReq.body ?? {};
+			const oResult = oValidations[ACTIONS[sMethod]]?.safeParse(oBody) ?? {
+				success: true,
+				data: oBody
+			};
+			if (!oResult.success) {
+				const { path, message } = oResult.error.issues[0];
+				throw new NanoError([...path, message].join(": "), 400);
+			}
+			const oRead = id ? {
+				page: {
+					where: { id },
+					limit: 1
+				},
+				answer: first
+			} : { answer: list };
+			return {
+				model: sModel,
+				table: oTable,
+				id,
+				body: oResult.data,
+				...oRead
+			};
+		} },
+		...oMethods
+	});
+}
+export { route as default };

package/build/health/index.d.ts

@@ -1,7 +1,5 @@
+import { NanoObject } from "../core/types/objects.js";
+import "../core/index.js";
 /** Health check: `GET /health` answers `{ status: "ok" }` while the server is up. */
-declare const _default: (options?: {
-  basePath?: string;
-} | undefined) => import("@nano-app/backend").PluginConfig<{
-  basePath?: string;
-}>;
+declare const _default: (options?: (NanoObject & import("@nano-app/backend").PluginOptions) | undefined) => import("@nano-app/backend").PluginConfig<NanoObject>;
 export { _default as default };

package/build/health/index.js

@@ -1,11 +1,12 @@
-import { createPlugin } from "@nano-app/backend";
-import { join } from "node:path";
+import { createPlugin, createRoute } from "@nano-app/backend";
 // health/index.ts
 /** Health check: `GET /health` answers `{ status: "ok" }` while the server is up. */
-var health_default = createPlugin((options) => ({
+var health_default = createPlugin(() => ({
 	name: "health",
-	basePath: options?.basePath ?? "/health",
-	stage: "before",
-	routesDir: join(import.meta.dirname, "routes")
+	basePath: "/health",
+	routes: { "/index": createRoute({
+		public: true,
+		GET: async () => ({ result: { status: "ok" } })
+	}) }
 }));
 export { health_default as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/plugins",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Official plugins for @nano-app/backend",
   "type": "module",
   "exports": {
@@ -64,8 +64,5 @@
     "zod": {
       "optional": true
     }
-  },
-  "dependencies": {
-    "express-rate-limit": "^8.7.3"
   }
 }

package/build/crud/routes/index.route.js

@@ -1,78 +0,0 @@
-import { NanoError, createRoute, isGranted } from "@nano-app/backend";
-import { eq } from "drizzle-orm";
-// crud/routes/index.route.ts
-/** Action of each method: its permission of Better Auth and the validation of its body */
-const ACTIONS = {
-	GET: "read",
-	QUERY: "read",
-	POST: "create",
-	PUT: "update",
-	DELETE: "delete"
-};
-/** Records a list answers when the request sends no `limit` */
-const DEFAULT_LIMIT = 100;
-/** The first record of a query or a write: 404 without it */
-function first(aRecords) {
-	if (!aRecords[0]) throw new NanoError("Not found", 404);
-	return { result: aRecords[0] };
-}
-/** Every record of a query */
-function list(aRecords) {
-	return { result: aRecords };
-}
-/** A list of the table, or one record by its id, with Drizzle's relational query of the body */
-async function read(_oReq, { db, onBeforeResult }) {
-	const { model, page, answer, body } = onBeforeResult;
-	return answer(await db.query[model].findMany({
-		limit: DEFAULT_LIMIT,
-		...body,
-		...page
-	}));
-}
-/** `GET` reads without parameters, `QUERY` with `QueryParams` as its body */
-var index_route_default = createRoute({
-	expression: "/:model{/:id}",
-	callbacks: { onBefore: async (oReq, sMethod, oParams) => {
-		const sModel = String(oReq.params.model);
-		const sAction = ACTIONS[sMethod];
-		const { id } = oReq.params;
-		const oTable = oParams.dbSchema[sModel];
-		if (!oParams.models.includes(sModel) || !oTable) throw new NanoError("Not found", 404);
-		if (!await isGranted(oParams, { [sModel]: [sAction] })) throw new NanoError("Forbidden", 403);
-		const oBody = oReq.body ?? {};
-		const oResult = (oParams.validations?.[sModel]?.[sAction])?.safeParse(oBody) ?? { data: oBody };
-		if (oResult.error) {
-			const { path, message } = oResult.error.issues[0];
-			throw new NanoError([...path, message].join(": "), 400);
-		}
-		const oRead = id ? {
-			page: {
-				where: { id },
-				limit: 1
-			},
-			answer: first
-		} : { answer: list };
-		return {
-			model: sModel,
-			table: oTable,
-			id,
-			body: oResult.data,
-			...oRead
-		};
-	} },
-	GET: read,
-	QUERY: read,
-	POST: async (_oReq, { db, onBeforeResult }) => {
-		const { table, body } = onBeforeResult;
-		return first(await db.insert(table).values(body).returning());
-	},
-	PUT: async (_oReq, { db, onBeforeResult }) => {
-		const { table, id, body } = onBeforeResult;
-		return first(await db.update(table).set(body).where(eq(table.id, id)).returning());
-	},
-	DELETE: async (_oReq, { db, onBeforeResult }) => {
-		const { table, id } = onBeforeResult;
-		return first(await db.delete(table).where(eq(table.id, id)).returning());
-	}
-});
-export { index_route_default as default };

package/build/health/routes/index.route.js

@@ -1,5 +0,0 @@
-import { createRoute } from "@nano-app/backend";
-// health/routes/index.route.ts
-/** Answers that the server is up */
-var index_route_default = createRoute({ GET: async () => ({ result: { status: "ok" } }) });
-export { index_route_default as default };

package/build/rate-limit/index.d.ts

@@ -1,14 +0,0 @@
-/**
- * Rate limit per client IP: each request spends a token of the client's bucket, refilled over time.
- * Covers the app's routes and the plugins listed after it.
- */
-declare const _default: (options?: {
-  capacity?: number;
-  refillPerSecond?: number;
-  message?: string;
-} | undefined) => import("@nano-app/backend").PluginConfig<{
-  capacity?: number;
-  refillPerSecond?: number;
-  message?: string;
-}>;
-export { _default as default };

package/build/rate-limit/index.js

@@ -1,44 +0,0 @@
-import { ipKeyGenerator } from "express-rate-limit";
-import { createPlugin } from "@nano-app/backend";
-// rate-limit/index.ts
-/**
-* Rate limit per client IP: each request spends a token of the client's bucket, refilled over time.
-* Covers the app's routes and the plugins listed after it.
-*/
-var rate_limit_default = createPlugin((options) => {
-	const { capacity = 100, refillPerSecond = 1, message = "Too many requests, please try again later." } = options ?? {};
-	return {
-		name: "rate-limit",
-		stage: "before",
-		routesDir: "",
-		callbacks: { onMount: async (oApp) => {
-			const fnRefill = (oBucket, iNow) => Math.min(capacity, oBucket.iTokens + (iNow - oBucket.iTime) / 1e3 * refillPerSecond);
-			const oBuckets = /* @__PURE__ */ new Map();
-			setInterval(() => {
-				const iNow = Date.now();
-				for (const [sIp, oBucket] of oBuckets) if (fnRefill(oBucket, iNow) >= capacity) oBuckets.delete(sIp);
-			}, 6e4).unref();
-			oApp.use((oReq, oRes, fnNext) => {
-				const sIp = ipKeyGenerator(oReq.ip ?? "");
-				const iNow = Date.now();
-				const iTokens = fnRefill(oBuckets.get(sIp) ?? {
-					iTokens: capacity,
-					iTime: iNow
-				}, iNow);
-				if (iTokens < 1) {
-					oRes.set("Retry-After", String(Math.ceil((1 - iTokens) / refillPerSecond)));
-					return fnNext({
-						status: 429,
-						message
-					});
-				}
-				oBuckets.set(sIp, {
-					iTokens: iTokens - 1,
-					iTime: iNow
-				});
-				fnNext();
-			});
-		} }
-	};
-});
-export { rate_limit_default as default };