webspresso 0.0.61 → 0.0.62

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

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.62",
   "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

@@ -397,6 +397,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)];

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

@@ -162,7 +162,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`**.
 
 ---