@nano-app/plugins 0.4.3 → 0.6.0

package/README.md

@@ -17,9 +17,13 @@ createNanoApp({ plugins: [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"`) |
+| 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 models listed in `models` (any other answers 404): `GET` and `QUERY` on `/api/<model>{/<id>}` → a list `{ result, count }` or one record, with `QueryParams` as the body of `QUERY`; `POST /api/<model>`, `PUT` and `DELETE` on `/api/<model>/<id>` → the record created, updated or deleted. `<id>` takes the type of the model's id (`Int`, `BigInt` or `String`). With Better Auth, each method asks for a permission on the model: `read` (`GET`, `QUERY`), `create`, `update`, `delete` | `models` (the published ones), `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)). 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` |
+
+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.
 
 ### Layout
 
@@ -119,7 +123,7 @@ At startup nano-app generates the plugin's client in `.nano-app/prisma-clients/<
 - Migrations only add: tables, nullable columns or columns with a default, indexes. Dropping or renaming takes two releases: stop using it first, remove it later.
 - The database user of the consumer needs to create tables in the plugin's `nano_*` schema.
 
-Handlers and callbacks receive that client as `params.db`. Type it with `createRoute<PrismaClient>`, passing your generated `PrismaClient`.
+Handlers and callbacks receive that client as `params.db`. Type it with `createRoute<{ db: PrismaClient }>`, passing your generated `PrismaClient`.
 
 ### What belongs in this repository
 

package/build/crud/Query.js

@@ -0,0 +1,62 @@
+// crud/Query.ts
+/** Records a list answers when the request sends no `top` */
+const DEFAULT_TOP = 100;
+/** Reads a model of the app's Prisma client with core's `QueryParams` */
+var Query = class Query {
+	/** A list of the model with its total, or one record by its `where` */
+	static async read(oModel, oQuery, oWhere) {
+		const oArgs = Query.toPrisma(oQuery);
+		if (oWhere) {
+			const { select, include } = oArgs;
+			return { result: await oModel.findUniqueOrThrow({
+				where: oWhere,
+				select,
+				include
+			}) };
+		}
+		const [aRecords, iCount] = await Promise.all([oModel.findMany(oArgs), oModel.count({ where: oArgs.where })]);
+		return {
+			result: aRecords,
+			count: iCount
+		};
+	}
+	/** `filter` → `where`, `orderby` → `orderBy`, `top`/`skip` → `take`/`skip`, `select` and `expand` → `select` or `include` */
+	static toPrisma(oQuery) {
+		const { filter, orderby, top, skip, select, expand } = oQuery;
+		const oInclude = expand ? Query.include(Query.list(expand)) : void 0;
+		const oSelect = select ? Query.fields(Query.list(select), oInclude) : void 0;
+		return {
+			where: filter,
+			orderBy: orderby && Object.entries(orderby).map(([sPath, sDirection]) => Query.nest(sPath.split("."), sDirection)),
+			take: top ?? DEFAULT_TOP,
+			skip,
+			select: oSelect,
+			include: oSelect ? void 0 : oInclude
+		};
+	}
+	/** `['user', 'name']`, `'asc'` → `{ user: { name: 'asc' } }` */
+	static nest(aPath, sValue) {
+		const [sField, ...aRest] = aPath;
+		return { [sField]: aRest.length ? Query.nest(aRest, sValue) : sValue };
+	}
+	/** `['user', 'posts.comments']` → `{ user: true, posts: { include: { comments: true } } }` */
+	static include(aPaths) {
+		const aRelations = [...new Set(aPaths.map((sPath) => sPath.split(".")[0]))];
+		return Object.fromEntries(aRelations.map((sRelation) => {
+			const aNested = aPaths.filter((sPath) => sPath.startsWith(`${sRelation}.`)).map((sPath) => sPath.slice(sRelation.length + 1));
+			return [sRelation, aNested.length ? { include: Query.include(aNested) } : true];
+		}));
+	}
+	/** `['id', 'name']` → `{ id: true, name: true }`, plus the relations to load */
+	static fields(aFields, oInclude) {
+		return {
+			...Object.fromEntries(aFields.map((sField) => [sField, true])),
+			...oInclude
+		};
+	}
+	/** `"a, b"` → `['a', 'b']` */
+	static list(sList) {
+		return sList.split(",").map((sItem) => sItem.trim());
+	}
+};
+export { Query as default };

package/build/crud/index.d.ts

@@ -0,0 +1,9 @@
+/** Automatic CRUD: the listed models of the app's database on `/api/<model>{/<id>}` */
+declare const _default: (options?: {
+  basePath?: string;
+  models: string[];
+} | undefined) => import("@nano-app/backend").PluginConfig<{
+  basePath?: string;
+  models: string[];
+}>;
+export { _default as default };

package/build/crud/index.js

@@ -0,0 +1,13 @@
+import { createPlugin } from "@nano-app/backend";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// crud/index.ts
+/** Automatic CRUD: the listed models of the app's database on `/api/<model>{/<id>}` */
+var crud_default = createPlugin((options) => ({
+	name: "crud",
+	basePath: options?.basePath ?? "/api",
+	stage: "after",
+	routesDir: resolve(dirname(fileURLToPath(import.meta.url)), "routes"),
+	options
+}));
+export { crud_default as default };

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

@@ -0,0 +1,48 @@
+import Query from "../Query.js";
+import { createRoute, isGranted } from "@nano-app/backend";
+// crud/routes/index.route.ts
+/** Permission of Better Auth that each method needs on the URL's model */
+const ACTIONS = {
+	GET: "read",
+	QUERY: "read",
+	POST: "create",
+	PUT: "update",
+	DELETE: "delete"
+};
+/** Conversion of the URL's id to the type of the model's id, when it is not a string */
+const ID_TYPES = {
+	Int: Number,
+	BigInt
+};
+/** `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 { id } = oReq.params;
+		if (!oParams.models.includes(sModel)) throw {
+			status: 404,
+			message: "Not found"
+		};
+		if (!await isGranted(oParams, { [sModel]: [ACTIONS[sMethod]] })) throw {
+			status: 403,
+			message: "Forbidden"
+		};
+		const oModel = oParams.db[sModel];
+		if (!id) return { model: oModel };
+		const sId = String(id);
+		return {
+			model: oModel,
+			where: { id: ID_TYPES[oModel.fields.id.typeName]?.(sId) ?? sId }
+		};
+	} },
+	GET: async (oReq, { onBeforeResult }) => Query.read(onBeforeResult?.model, oReq.body ?? {}, onBeforeResult?.where),
+	QUERY: async (oReq, { onBeforeResult }) => Query.read(onBeforeResult?.model, oReq.body ?? {}, onBeforeResult?.where),
+	POST: async (oReq, { onBeforeResult }) => ({ result: await onBeforeResult?.model.create({ data: oReq.body }) }),
+	PUT: async (oReq, { onBeforeResult }) => ({ result: await onBeforeResult?.model.update({
+		where: onBeforeResult.where,
+		data: oReq.body
+	}) }),
+	DELETE: async (_oReq, { onBeforeResult }) => ({ result: await onBeforeResult?.model.delete({ where: onBeforeResult.where }) })
+});
+export { index_route_default as default };

package/build/health/index.js

@@ -1,6 +1,6 @@
+import { createPlugin } from "@nano-app/backend";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createPlugin } from "@nano-app/backend";
 // health/index.ts
 /** Health check: `GET /health` answers `{ status: "ok" }` while the server is up. */
 var health_default = createPlugin((options) => ({

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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,43 @@
+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 = 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/plugins",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Official plugins for @nano-app/backend",
   "type": "module",
   "exports": {
@@ -37,18 +37,20 @@
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "peerDependencies": {
-    "@nano-app/backend": ">=0.9.0"
+    "@nano-app/backend": ">=0.12.5"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^21.0.4",
     "@nano-app/backend": "workspace:*",
     "@prisma/adapter-pg": "^7.10.1",
     "@prisma/client": "^7.10.1",
     "@types/node": "^26.6.6",
     "@types/pg": "^8.23.1",
     "glob": "^14.0.3",
+    "next": "^16.4.3",
     "pg": "^8.23.1",
     "prisma": "^7.10.1",
-    "tsdown": "^0.23.4",
+    "tsdown": "^0.23.5",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   }