webspresso 0.0.62 → 0.0.63

package/README.md

@@ -1030,7 +1030,40 @@ module.exports = async function handler(req, res) {
 };
 ```
 
-**With Schema Validation:**
+**Object export (`handler`, `middleware`, `schema`):**
+
+Use a single export object when you need **named middleware** from `createApp({ middlewares })` and/or a **Zod** `schema`. Order at runtime: **`req.db`** (if configured) → **schema** (`req.input`) → **middleware** chain → **handler**.
+
+```javascript
+// pages/api/search.post.js
+module.exports = {
+  middleware: ['requireAuth'],
+  schema: ({ z }) => ({
+    body: z.object({ q: z.string() }),
+  }),
+  handler: async (req, res) => {
+    const { q } = req.input.body;
+    const results = [];
+    return res.json({ results, q });
+  },
+};
+```
+
+Register `requireAuth` (and any other names) on the app:
+
+```javascript
+createApp({
+  pagesDir: './pages',
+  middlewares: {
+    requireAuth: (req, res, next) => {
+      if (!req.session?.user) return res.status(401).json({ error: 'Unauthorized' });
+      next();
+    },
+  },
+});
+```
+
+**With Schema Validation (same object shape):**
 
 ```javascript
 // pages/api/posts.post.js
@@ -1066,7 +1099,25 @@ module.exports = {
 | `query` | Validates query string parameters |
 | `response` | Response schema (for documentation, not enforced) |
 
-All schemas use [Zod](https://zod.dev) for validation. Invalid requests throw a `ZodError` which can be caught by error handlers.
+All schemas use [Zod](https://zod.dev) for validation. Invalid requests receive **`400 JSON`**: `{ error: 'Validation Error', issues: [...] }` (no `handler` / `middleware` run).
+
+For **nanoid** route parameters (same alphabet and default length as **`generateNanoid`** / **`zdb.nanoid()`**), use **`z.nanoid()`** on the `z` passed into your API schema (Webspresso extends it; no extra import). Optional: **`z.nanoid(12)`** or **`z.nanoid({ maxLength: 12 })`** (matches **`zdb.nanoid({ maxLength })`**). For scripts or tests outside `schema: ({ z })`, **`zodNanoid(z, size?)`** and **`extendZ(z)`** are exported from `webspresso`.
+
+```javascript
+module.exports = {
+  schema: ({ z }) => ({
+    params: z.object({
+      id: z.nanoid(),                  // default 21 chars
+      shortId: z.nanoid(12),           // numeric length
+      other: z.nanoid({ maxLength: 8 }), // zdb-style options
+    }),
+  }),
+  async handler(req, res) {
+    const { id } = req.input.params;
+    // ...
+  },
+};
+```
 
 **Dynamic Route with Params Validation:**
 

package/core/compileSchema.js

@@ -4,8 +4,12 @@
  */
 
 const z = require('zod');
+const { extendZ } = require('./orm/utils/nanoid');
 const schemaCache = require('../utils/schemaCache');
 
+/** Zod plus `z.nanoid()` for API schemas (does not mutate the global `z`). */
+const zForApi = extendZ(z);
+
 /**
  * Compile schema from an API module
  * @param {string} filePath - Absolute file path to API module
@@ -32,8 +36,8 @@ function compileSchema(filePath, apiModule) {
     throw new Error(`Schema in ${filePath} must be a function`);
   }
 
-  // Call schema function with { z }
-  const compiled = schemaFn({ z });
+  // Call schema function with { z } (extended with z.nanoid, same as generateNanoid / zdb.nanoid)
+  const compiled = schemaFn({ z: zForApi });
 
   // Validate compiled schema structure
   if (compiled !== null && typeof compiled !== 'object') {

package/core/orm/index.js

@@ -14,7 +14,7 @@ const { createSeeder } = require('./seeder');
 const { createScopeContext } = require('./scopes');
 const { ModelEvents, Hooks, HookCancellationError, createEventContext } = require('./events');
 const { omitHiddenColumns, sanitizeForOutput } = require('./utils');
-const { generateNanoid } = require('./utils/nanoid');
+const { generateNanoid, zodNanoid, extendZ } = require('./utils/nanoid');
 
 /**
  * Create a database instance
@@ -275,6 +275,8 @@ module.exports = {
   extractColumnsFromSchema,
   getColumnMeta,
   generateNanoid,
+  zodNanoid,
+  extendZ,
   // Output sanitization (exclude hidden columns from API/templates)
   omitHiddenColumns,
   sanitizeForOutput,

package/core/orm/utils/nanoid.js

@@ -24,7 +24,60 @@ function generateNanoid(size = 21) {
   return id;
 }
 
+/**
+ * Zod schema for IDs produced by {@link generateNanoid} (same default alphabet & length).
+ * Prefer **`z.nanoid()`** in API `schema: ({ z }) => …`; use this when building Zod schemas outside compiled routes.
+ * @param {typeof import('zod').z} z - Zod instance (from `schema: ({ z }) => …`)
+ * @param {number} [size=21]
+ */
+function zodNanoid(z, size = 21) {
+  const n = Math.max(1, Math.floor(size));
+  const alphabet = new Set(URL_ALPHABET);
+  return z.string().length(n).refine((s) => [...s].every((ch) => alphabet.has(ch)), {
+    message: `Expected ${n}-character nanoid (default URL alphabet)`,
+  });
+}
+
+/**
+ * @param {unknown} arg - `undefined` → 21; number → length; `{ maxLength }` (zdb-compatible)
+ * @returns {number}
+ */
+function resolveNanoidSize(arg) {
+  if (arg === undefined) return 21;
+  if (arg === null) return 21;
+  if (typeof arg === 'number' && !Number.isNaN(arg)) {
+    return Math.max(1, Math.floor(arg));
+  }
+  if (typeof arg === 'object' && arg !== null && 'maxLength' in arg) {
+    const n = /** @type {{ maxLength?: unknown }} */ (arg).maxLength;
+    if (typeof n === 'number' && !Number.isNaN(n)) {
+      return Math.max(1, Math.floor(n));
+    }
+  }
+  return 21;
+}
+
+/**
+ * Wraps Zod's `z` with **`z.nanoid()`** / **`z.nanoid(12)`** / **`z.nanoid({ maxLength: 12 })`**
+ * without mutating the global `z` object. Used by API `schema: ({ z }) => …`.
+ * @param {typeof import('zod').z} zod
+ */
+function extendZ(zod) {
+  return new Proxy(zod, {
+    get(target, prop, receiver) {
+      if (prop === 'nanoid') {
+        return function nanoid(arg) {
+          return zodNanoid(zod, resolveNanoidSize(arg));
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}
+
 module.exports = {
   generateNanoid,
+  zodNanoid,
+  extendZ,
   URL_ALPHABET,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {

package/src/file-router.js

@@ -5,6 +5,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const { ZodError } = require('zod');
+const { compileSchema, invalidateSchema } = require('../core/compileSchema');
+const { applySchema } = require('../core/applySchema');
 const { createHelpers } = require('./helpers');
 
 // Cache for i18n files (key: filePath, value: { mtime, data })
@@ -412,6 +415,30 @@ function mountPages(app, options) {
         const fn = typeof currentHandler === 'function' 
           ? currentHandler 
           : currentHandler.default || currentHandler.handler;
+
+        if (isDev) {
+          invalidateSchema(route.fullPath);
+        }
+        let compiledSchema;
+        try {
+          compiledSchema = compileSchema(route.fullPath, currentHandler);
+        } catch (schemaErr) {
+          console.error(`API schema compile error ${route.routePath}:`, schemaErr);
+          res.status(500).json({ error: 'Internal Server Error', message: schemaErr.message });
+          return;
+        }
+
+        try {
+          applySchema(req, compiledSchema);
+        } catch (err) {
+          if (err instanceof ZodError) {
+            return res.status(400).json({
+              error: 'Validation Error',
+              issues: err.issues,
+            });
+          }
+          throw err;
+        }
         
         // Run middleware if defined
         const mwConfig = isDev ? currentHandler.middleware : routeMiddleware;

package/templates/skills/webspresso-usage/SKILL.md

@@ -102,9 +102,11 @@ project/
 **Shapes**
 
 1. **Function** — `module.exports = async (req, res) => { ... }`
-2. **Object** — `schema`, `handler`, optional `middleware`
+2. **Object** — **`handler`**, optional **`middleware`** (names from **`createApp({ middlewares })`**), optional **`schema`**
 
-**Zod** — `schema: ({ z }) => ({ body, query, params, response })` → validated data on **`req.input`**.
+**Order:** `req.db` (if any) → **Zod** `schema` → **`middleware`** → **`handler`**.
+
+**Zod** — `schema: ({ z }) => ({ body, query, params, response })` → **`req.input`**; invalid → **400** `{ error: 'Validation Error', issues }`.
 
 ---