@nano-app/plugins 0.8.0 → 0.9.0

package/README.md

@@ -20,14 +20,36 @@ createNanoApp({ plugins: [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 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 on the table alone (`where`, `columns`, `orderBy`, `limit`, `offset`): a relation in `where` or `with` answers 400; `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), `schema` (the app's Drizzle schema, as in `mainPlugin.database`), `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` |
+| `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` |
 
 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.
 
+### crud and the bodies
+
+`crud` sends each body to Drizzle as it came: any column of the table can be written, and a `QUERY` can ask for any `limit` (100 without one). What a body may bring is up to the app: `validations` takes, per model, a [zod](https://zod.dev) schema by action, the same names as the permissions: `read` (the body of `QUERY`, and `{}` for `GET`), `create` (`POST`) and `update` (`PUT`). A body that breaks its validation answers 400 with the field and the message of zod; one that passes goes on as zod gives it, so a validation also drops the keys it does not name and sets its defaults. [`drizzle-orm/zod`](https://orm.drizzle.team/docs/zod) builds them from the table:
+
+```ts
+import { createInsertSchema, createUpdateSchema } from 'drizzle-orm/zod';
+import { z } from 'zod';
+import * as schema from './db/schema';
+
+crud({
+  models: ['note'],
+  dbSchema: schema,
+  validations: {
+    note: {
+      create: createInsertSchema(schema.note).omit({ id: true }),
+      update: createUpdateSchema(schema.note).omit({ id: true }),
+      read: z.looseObject({ limit: z.number().max(50).default(20) }),
+    },
+  },
+});
+```
+
 ### crud and related tables
 
-A `crud` query never leaves its table: its client knows the app's tables but none of their relations, so a relation in `where` or `with` answers 400. Better Auth's tables (`user`, `account` with its password hashes, `session` with its tokens) are reached only when they are in `models`; never publish `account`, `session` or `verification`. What needs related tables goes in a route of your own.
+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.
 
 ### Layout
 

package/build/crud/index.d.ts

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

package/build/crud/index.js

@@ -1,13 +1,12 @@
 import { createPlugin } from "@nano-app/backend";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 // crud/index.ts
-/** Automatic CRUD: the listed tables of the app's schema on `/api/<model>{/<id>}` */
+/** Automatic CRUD: the listed tables 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"),
+	routesDir: join(import.meta.dirname, "routes"),
 	options
 }));
 export { crud_default as default };

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

@@ -1,8 +1,7 @@
 import { NanoError, createRoute, isGranted } from "@nano-app/backend";
-import { defineRelations, eq } from "drizzle-orm";
-import { drizzle } from "drizzle-orm/node-postgres";
+import { eq } from "drizzle-orm";
 // crud/routes/index.route.ts
-/** Permission of Better Auth that each method needs on the URL's table */
+/** Action of each method: its permission of Better Auth and the validation of its body */
 const ACTIONS = {
 	GET: "read",
 	QUERY: "read",
@@ -17,48 +16,59 @@ function first(aRecords) {
 	if (!aRecords[0]) throw new NanoError("Not found", 404);
 	return { result: aRecords[0] };
 }
-/** A list of the table, or one record by its id, with Drizzle's relational query of the body on the table alone */
-async function read(oReq, { db, schema, onBeforeResult }) {
-	const { model, id } = onBeforeResult ?? {};
-	const oBody = oReq.body ?? {};
-	const { relations: _oRelations, ...oTables } = schema;
-	const oNoRelations = defineRelations(oTables);
-	const oQuery = drizzle({
-		client: db.$client,
-		relations: oNoRelations
-	}).query[model];
-	if (id) return first(await oQuery.findMany({
-		...oBody,
-		where: { id },
-		limit: 1
+/** 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
 	}));
-	return { result: await oQuery.findMany({
-		...oBody,
-		where: oBody.where ?? {},
-		limit: oBody.limit ?? DEFAULT_LIMIT
-	}) };
 }
 /** `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.schema?.[sModel];
+		const oTable = oParams.dbSchema[sModel];
 		if (!oParams.models.includes(sModel) || !oTable) throw new NanoError("Not found", 404);
-		if (!await isGranted(oParams, { [sModel]: [ACTIONS[sMethod]] })) throw new NanoError("Forbidden", 403);
+		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
+			id,
+			body: oResult.data,
+			...oRead
 		};
 	} },
 	GET: read,
 	QUERY: read,
-	POST: async (oReq, { db, onBeforeResult }) => first(await db.insert(onBeforeResult?.table).values(oReq.body).returning()),
-	PUT: async (oReq, { db, onBeforeResult }) => {
-		const { table, id } = onBeforeResult ?? {};
-		return first(await db.update(table).set(oReq.body).where(eq(table.id, id)).returning());
+	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 ?? {};

package/build/health/index.js

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

package/build/rate-limit/index.js

@@ -1,3 +1,4 @@
+import { ipKeyGenerator } from "express-rate-limit";
 import { createPlugin } from "@nano-app/backend";
 // rate-limit/index.ts
 /**
@@ -18,7 +19,7 @@ var rate_limit_default = createPlugin((options) => {
 				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 sIp = ipKeyGenerator(oReq.ip ?? "");
 				const iNow = Date.now();
 				const iTokens = fnRefill(oBuckets.get(sIp) ?? {
 					iTokens: capacity,

package/build/types/crud.d.ts

@@ -0,0 +1,10 @@
+import { ZodType } from "zod";
+/** Validations of a model: a zod schema by action, each one optional */
+export type CrudValidations = {
+  /** Body of a `QUERY`, and `{}` for a `GET` */
+  read?: ZodType;
+  /** Body of a `POST` */
+  create?: ZodType;
+  /** Body of a `PUT` */
+  update?: ZodType;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/plugins",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Official plugins for @nano-app/backend",
   "type": "module",
   "exports": {
@@ -38,7 +38,8 @@
   },
   "peerDependencies": {
     "@nano-app/backend": ">=0.15.0",
-    "drizzle-orm": "^1.0.0-rc.5"
+    "drizzle-orm": "^1.0.0-rc.5",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
@@ -52,11 +53,18 @@
     "pg": "^8.23.1",
     "tsdown": "^0.23.5",
     "tsx": "^4.23.15",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "zod": "^4.6.7"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
+  },
+  "dependencies": {
+    "express-rate-limit": "^8.7.3"
   }
 }