webspresso 0.0.65 → 0.0.66

package/plugins/orm-cache-admin/api-handlers.js

@@ -0,0 +1,78 @@
+/**
+ * Admin API for ORM cache metrics and purge
+ * @module plugins/orm-cache-admin/api-handlers
+ */
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db
+ */
+function createOrmCacheAdminHandlers({ db }) {
+  function requireCache(res) {
+    if (!db.cache) {
+      res.status(503).json({ error: 'ORM cache is not enabled on this database' });
+      return null;
+    }
+    return db.cache;
+  }
+
+  async function getStats(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      res.json(cache.getMetrics());
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postPurge(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.purge();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postInvalidate(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      const body = req.body && typeof req.body === 'object' ? req.body : {};
+      if (Array.isArray(body.tags) && body.tags.length > 0) {
+        cache.invalidateTags(body.tags.map(String));
+        return res.json({ ok: true, mode: 'tags' });
+      }
+      if (typeof body.model === 'string' && body.model.trim()) {
+        cache.invalidateModel(body.model.trim());
+        return res.json({ ok: true, mode: 'model' });
+      }
+      res.status(400).json({ error: 'Provide { model: string } or { tags: string[] }' });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postResetMetrics(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.resetMetrics();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  return {
+    getStats,
+    postPurge,
+    postInvalidate,
+    postResetMetrics,
+  };
+}
+
+module.exports = { createOrmCacheAdminHandlers };

package/plugins/orm-cache-admin/index.js

@@ -0,0 +1,72 @@
+/**
+ * ORM Cache Admin — metrics, purge, invalidate (requires admin-panel + db.cache)
+ * @module plugins/orm-cache-admin
+ */
+
+const { createOrmCacheAdminHandlers } = require('./api-handlers');
+const { generateOrmCacheAdminComponent } = require('./admin-component');
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db - From createDatabase({ cache: true })
+ */
+function ormCacheAdminPlugin(options = {}) {
+  const { db } = options;
+
+  if (!db) {
+    throw new Error('orm-cache-admin plugin requires `db` (database instance from createDatabase)');
+  }
+
+  return {
+    name: 'orm-cache-admin',
+    version: '1.0.0',
+    description: 'Admin UI for ORM query cache metrics and purge',
+    dependencies: { 'admin-panel': '*' },
+
+    register() {},
+
+    onRoutesReady(ctx) {
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        console.warn('[orm-cache-admin] admin-panel not found, skipping registration');
+        return;
+      }
+
+      if (!db.cache) {
+        console.warn('[orm-cache-admin] db.cache is disabled; enable createDatabase({ cache: true })');
+        return;
+      }
+
+      const handlers = createOrmCacheAdminHandlers({ db });
+
+      adminApi.registerModule({
+        id: 'orm-cache',
+        pages: [{
+          id: 'orm-cache',
+          title: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          component: generateOrmCacheAdminComponent(),
+        }],
+        menu: [{
+          id: 'orm-cache',
+          label: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          order: 15,
+        }],
+        api: {
+          prefix: '/orm-cache',
+          routes: [
+            { method: 'get', path: '/stats', handler: handlers.getStats },
+            { method: 'post', path: '/purge', handler: handlers.postPurge },
+            { method: 'post', path: '/invalidate', handler: handlers.postInvalidate },
+            { method: 'post', path: '/metrics/reset', handler: handlers.postResetMetrics },
+          ],
+        },
+      });
+    },
+  };
+}
+
+module.exports = ormCacheAdminPlugin;

package/src/file-router.js

@@ -276,9 +276,58 @@ function detectLocale(req) {
 }
 
 /**
- * Resolve middleware from config - supports both functions and named strings
- * @param {Array} middlewareConfig - Array of middleware functions or names
- * @param {Object} middlewareRegistry - Named middleware registry
+ * True when the registry entry is (options) => (req, res, next) => …
+ * Express handlers typically have length >= 2 (req, res) or 3 (req, res, next).
+ */
+function isMiddlewareFactory(fn) {
+  return typeof fn === 'function' && fn.length <= 1;
+}
+
+/**
+ * Resolve a named middleware from createApp({ middlewares }).
+ * @param {string} name
+ * @param {Function} entry
+ * @param {boolean} fromTuple - true when route used ['name', options]
+ * @param {unknown} tupleOptions - second element of the tuple (only when fromTuple)
+ * @param {Object} middlewareRegistry - for error messages
+ * @returns {Function} Express middleware
+ */
+function resolveNamedMiddleware(name, entry, fromTuple, tupleOptions, middlewareRegistry) {
+  if (!entry) {
+    throw new Error(`Middleware "${name}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
+  }
+  if (typeof entry !== 'function') {
+    throw new Error(`Middleware "${name}" must be a function`);
+  }
+
+  if (fromTuple) {
+    if (!isMiddlewareFactory(entry)) {
+      throw new Error(
+        `Middleware "${name}" must be a factory (options) => (req, res, next) => … when using ["${name}", options] tuple form`
+      );
+    }
+    const produced = entry(tupleOptions);
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  if (isMiddlewareFactory(entry)) {
+    const produced = entry({});
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  return entry;
+}
+
+/**
+ * Resolve middleware from config — functions, string names, or [name, options] tuples
+ * @param {Array} middlewareConfig - middleware functions, names, or ['name', options] tuples
+ * @param {Object} middlewareRegistry - Named middleware registry (plain handlers or option factories)
  * @returns {Array} Array of resolved middleware functions
  */
 function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
@@ -292,17 +341,17 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
     }
     
     if (typeof mw === 'string') {
-      const resolved = middlewareRegistry[mw];
-      if (!resolved) {
-        throw new Error(`Middleware "${mw}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
-      }
-      if (typeof resolved !== 'function') {
-        throw new Error(`Middleware "${mw}" must be a function`);
-      }
-      return resolved;
+      return resolveNamedMiddleware(mw, middlewareRegistry[mw], false, undefined, middlewareRegistry);
+    }
+
+    if (Array.isArray(mw) && mw.length === 2 && typeof mw[0] === 'string') {
+      const name = mw[0];
+      return resolveNamedMiddleware(name, middlewareRegistry[name], true, mw[1], middlewareRegistry);
     }
     
-    throw new Error(`Invalid middleware at index ${index}: must be a function or string name`);
+    throw new Error(
+      `Invalid middleware at index ${index}: must be a function, string name, or [name, options] tuple`
+    );
   });
 }
 

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

@@ -164,6 +164,8 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
 
+**Query cache (optional):** `createDatabase({ ..., cache: true })` or `cache: { defaultStrategy: 'auto'|'smart', memory: { maxEntries, defaultTtlMs }, provider?: custom }`. Opt-in per model: `defineModel({ ..., cache: 'auto'|'smart'|true })`. API: `db.cache` → `getMetrics()`, `purge()`, `invalidateModel(name)`, `invalidateTags(tags[])`, `resetMetrics()`. Reads bypass cache when using a transaction knex. Admin UI: `ormCacheAdminPlugin({ db })` (needs `admin-panel` and `cache` enabled).
+
 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`**.
 
 ---
@@ -180,6 +182,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `auditLogPlugin` | Admin mutation audit trail |
 | `recaptchaPlugin` | v2/v3 + middleware |
 | `seoCheckerPlugin` | Dev SEO panel |
+| `ormCacheAdminPlugin` | Admin page for ORM cache metrics / purge / invalidate (`db.cache` required) |
 
 **Custom plugin:** `name`, `version`, `register(ctx)`, `onRoutesReady(ctx)` — use `ctx.app`, `ctx.db`, `ctx.addHelper`, `ctx.addRoute`, `ctx.usePlugin('other')`. Plugin failures **warn**; app keeps running.