@nano-app/plugins 0.7.1 → 0.9.0

package/README.md

@@ -20,19 +20,44 @@ 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 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` |
+| `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 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
 
 ```
 plugins/
 └── <name>/
     ├── index.ts        default-exports the plugin factory: the import path
-    ├── schema.prisma   its tables, when it has any
-    ├── migrations/     their migrations, applied at startup
+    ├── schema.ts       its tables, when it has any, in the Postgres schema nano_<name>
     └── routes/         *.route.ts, mounted under the plugin's basePath
 ```
 
@@ -110,20 +135,9 @@ Use MIT or Apache-2.0 if you want the plugin listed from this repo later. Open a
 
 ### Database
 
-Optional. Set `database: { enabled: true, schemaPath }` on the plugin config. The schema must be PostgreSQL. Schemas starting with `nano_` are reserved for the official plugins: a schema inside the `@nano-app/plugins` package declares only `nano_*` schemas, and every other schema declares none.
-
-At startup nano-app generates the plugin's client in `.nano-app/prisma-clients/<name>` (again only when the schema changed) and checks that every model can be read.
-
-- **A plugin of yours, or from another package:** its tables are applied with Prisma by whoever installs it, like the app's schema.
-- **An official plugin:** nano-app also migrates it, so the consumer runs nothing. Its schema ships in `build/<name>/schema.prisma` with a `migrations/` folder next to it. At startup `prisma migrate deploy` applies the pending ones to the plugin's first `nano_*` schema, where its history (`_prisma_migrations`) lives apart from the app's. Each migration runs once, in a transaction, one instance at a time.
-
-#### Migrations of an official plugin
-
-- Every schema change ships its own `migrations/<timestamp>_<name>/migration.sql`, reviewed like code. A published migration is never edited.
-- 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.
+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.
 
-Handlers and callbacks receive that client as `params.db`. Type it with `createRoute<{ db: PrismaClient }>`, passing your generated `PrismaClient`.
+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`.
 
 ### What belongs in this repository
 

package/build/crud/index.d.ts

@@ -1,9 +1,15 @@
-/** Automatic CRUD: the listed models of the app's database on `/api/<model>{/<id>}` */
+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;
+  validations?: NanoObject<CrudValidations>;
 } | undefined) => import("@nano-app/backend").PluginConfig<{
   basePath?: string;
   models: string[];
+  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 models of the app's database 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,7 +1,7 @@
-import Query from "../Query.js";
 import { NanoError, createRoute, isGranted } from "@nano-app/backend";
+import { eq } from "drizzle-orm";
 // crud/routes/index.route.ts
-/** Permission of Better Auth that each method needs on the URL's model */
+/** Action of each method: its permission of Better Auth and the validation of its body */
 const ACTIONS = {
 	GET: "read",
 	QUERY: "read",
@@ -9,38 +9,70 @@ const ACTIONS = {
 	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
-};
-/** Reads a list, or one record, with the `QueryParams` of the body */
-async function read(oReq, { onBeforeResult }) {
-	return Query.read(onBeforeResult?.model, oReq.body ?? {}, onBeforeResult?.where);
+/** 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;
-		if (!oParams.models.includes(sModel)) throw new NanoError("Not found", 404);
-		if (!await isGranted(oParams, { [sModel]: [ACTIONS[sMethod]] })) throw new NanoError("Forbidden", 403);
-		const oModel = oParams.db[sModel];
-		if (!id) return { model: oModel };
-		const sId = String(id);
+		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: oModel,
-			where: { id: ID_TYPES[oModel.fields.id.typeName]?.(sId) ?? sId }
+			model: sModel,
+			table: oTable,
+			id,
+			body: oResult.data,
+			...oRead
 		};
 	} },
 	GET: read,
 	QUERY: read,
-	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 }) })
+	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/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.7.1",
+  "version": "0.9.0",
   "description": "Official plugins for @nano-app/backend",
   "type": "module",
   "exports": {
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "test": "tsx --env-file-if-exists=../.env --test tests/*.test.ts",
+    "test": "tsx --env-file-if-exists=../.env --test --test-concurrency=1 tests/*.test.ts",
     "prepublishOnly": "pnpm run build"
   },
   "keywords": [
@@ -37,21 +37,34 @@
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "peerDependencies": {
-    "@nano-app/backend": ">=0.15.0"
+    "@nano-app/backend": ">=0.15.0",
+    "drizzle-orm": "^1.0.0-rc.5",
+    "zod": "^4.6.7"
   },
   "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",
+    "drizzle-kit": "^1.0.0-rc.5",
+    "drizzle-orm": "^1.0.0-rc.5",
     "glob": "^14.0.4",
     "next": "^16.4.5",
     "pg": "^8.23.1",
-    "prisma": "^7.10.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"
   }
 }

package/build/crud/Query.js

@@ -1,62 +0,0 @@
-// 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 };