webspresso 0.0.61 → 0.0.63

package/README.md

@@ -336,7 +336,7 @@ Creates and configures the Express app.
 - `pagesDir` (required): Path to pages directory
 - `viewsDir` (optional): Path to views/layouts directory
 - `publicDir` (optional): Path to public/static directory
-- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions
+- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions; also registered for [`getDb()` / `getAppContext()`](#app-context-getdb-hasdb-getappcontext) below
 - `logging` (optional): Enable request logging (default: true in development)
 - `helmet` (optional): Helmet security configuration
   - `true` or `undefined`: Use default secure configuration
@@ -386,6 +386,54 @@ module.exports = {
 };
 ```
 
+### App context (`req.db`, `getDb`, `attachDbMiddleware`)
+
+With **`createApp({ db })`**, file-based **API** routes (`pages/api/*.js`) get the same ORM instance on **`req.db`** before your **`middleware`** array and the handler run — no extra `require` in the handler:
+
+```javascript
+module.exports = async function handler(req, res) {
+  if (!req.db) {
+    return res.status(503).json({ error: 'Database not configured' });
+  }
+  const posts = await req.db.getRepository('Post').query().limit(10).list();
+  res.json(posts);
+};
+
+module.exports.middleware = ['auth']; // can use req.db too
+```
+
+The framework also registers that instance for **non-request** code (scripts, jobs) and for tests:
+
+```javascript
+const { getDb, hasDb } = require('webspresso');
+// hasDb() / getDb() — getDb() throws if createApp had no db
+```
+
+For routes you add manually in **`setupRoutes`**, run **`attachDbMiddleware`** early so those handlers get `req.db`:
+
+```javascript
+const { createApp, attachDbMiddleware } = require('webspresso');
+
+createApp({
+  pagesDir: './pages',
+  db,
+  setupRoutes(app) {
+    app.use(attachDbMiddleware);
+    app.get('/custom/api', (req, res) => res.json({ ok: !!req.db }));
+  },
+});
+```
+
+| Export | Role |
+|--------|------|
+| `req.db` | Set on each API request when `createApp({ db })` was used (file-based API routes + after `attachDbMiddleware`) |
+| `getDb()` | Same instance as `req.db`; **throws** if no `db` was passed to `createApp` |
+| `hasDb()` | `true` if `createApp` was given `db` |
+| `getAppContext()` | `{ db }` — `db` may be `null` |
+| `attachDbMiddleware` | Express middleware to populate `req.db` for non–file-router routes |
+| `resetAppContext()` | Clears context (mainly for tests) |
+| `setAppContext(partial)` | Low-level merge; normally only `createApp` uses this |
+
 **Custom Error Pages:**
 
 ```javascript
@@ -982,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
@@ -1018,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/index.js

@@ -3,6 +3,14 @@
  */
 
 const { createApp } = require('./src/server');
+const {
+  attachDbMiddleware,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  setAppContext,
+} = require('./src/app-context');
 const { 
   mountPages, 
   filePathToRoute, 
@@ -35,6 +43,13 @@ const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlu
 module.exports = {
   // Main API
   createApp,
+
+  attachDbMiddleware,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  setAppContext,
   
   // Router utilities (for advanced use)
   mountPages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.61",
+  "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/app-context.js

@@ -0,0 +1,75 @@
+/**
+ * Process-wide app context set by createApp() — use from API handlers, jobs, etc.
+ * @module src/app-context
+ */
+
+/** @type {{ db: object|null }} */
+let context = {
+  db: null,
+};
+
+/**
+ * Merge into the current context (typically called once from createApp).
+ * @param {{ db?: object|null }} partial
+ */
+function setAppContext(partial) {
+  context = { ...context, ...partial };
+}
+
+/**
+ * @returns {{ db: object|null }}
+ */
+function getAppContext() {
+  return context;
+}
+
+/**
+ * Database instance passed to createApp({ db }) (Knex + ORM helpers).
+ * @returns {object}
+ * @throws {Error} If createApp was not given a db instance
+ */
+function getDb() {
+  if (!context.db) {
+    throw new Error(
+      'No database registered. Create a DB with createDatabase(), then pass it to createApp({ db }). ' +
+        'Or use hasDb() before calling getDb().'
+    );
+  }
+  return context.db;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasDb() {
+  return context.db != null;
+}
+
+/**
+ * Clear context (e.g. between tests).
+ */
+function resetAppContext() {
+  context = { db: null };
+}
+
+/**
+ * Express middleware: sets `req.db` from registered app context.
+ * File-based `pages/api/*` routes attach this automatically; use in `setupRoutes`
+ * for manually registered handlers that need `req.db`.
+ * @type {import('express').RequestHandler}
+ */
+function attachDbMiddleware(req, res, next) {
+  if (context.db != null) {
+    req.db = context.db;
+  }
+  next();
+}
+
+module.exports = {
+  setAppContext,
+  getAppContext,
+  getDb,
+  hasDb,
+  resetAppContext,
+  attachDbMiddleware,
+};

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 })
@@ -397,6 +400,11 @@ function mountPages(app, options) {
     
     app[route.method](route.routePath, async (req, res, next) => {
       try {
+        // Same instance as createApp({ db }) / getAppContext().db — available to handler & route middleware
+        if (db != null) {
+          req.db = db;
+        }
+
         // Reload handler in dev mode
         if (isDev && require.cache[require.resolve(route.fullPath)]) {
           delete require.cache[require.resolve(route.fullPath)];
@@ -407,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/src/server.js

@@ -8,6 +8,7 @@ const helmet = require('helmet');
 const nunjucks = require('nunjucks');
 const timeout = require('connect-timeout');
 
+const { setAppContext } = require('./app-context');
 const { mountPages } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
@@ -200,6 +201,8 @@ function createApp(options = {}) {
   if (!pagesDir) {
     throw new Error('pagesDir is required');
   }
+
+  setAppContext({ db: options.db ?? null });
   
   const app = express();
   

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 }`.
 
 ---
 
@@ -162,7 +164,7 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
 
-Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins.
+Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins. **`pages/api/`** handlers receive **`req.db`** (and route **`middleware`** runs after it). Outside requests, use **`getDb()`** / **`hasDb()`**; for **`setupRoutes`**-only routes, use **`attachDbMiddleware`**.
 
 ---