webspresso 0.0.64 → 0.0.66

package/core/orm/repository.js

@@ -22,9 +22,10 @@ const { getJsonColumns, serializeJsonFields, deserializeJsonFields } = require('
  * @param {import('./types').ModelDefinition} model - Model definition
  * @param {import('knex').Knex|import('knex').Knex.Transaction} knex - Knex instance
  * @param {import('./types').ScopeContext} [initialContext] - Initial scope context
+ * @param {import('./cache/layer').OrmCacheLayer|null} [cacheLayer] - Optional ORM cache layer
  * @returns {import('./types').Repository}
  */
-function createRepository(model, knex, initialContext) {
+function createRepository(model, knex, initialContext, cacheLayer = null) {
   const scopeContext = initialContext || createScopeContext();
   const jsonColumns = getJsonColumns(model);
 
@@ -49,40 +50,59 @@ function createRepository(model, knex, initialContext) {
     const ctx = createEventContext(model.name, 'find');
     const query = { [model.primaryKey]: id };
 
-    // Emit beforeFind
-    if (emitEvents) {
-      await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, query, ctx);
-      if (ctx.isCancelled) {
-        throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
+    async function loadFromDb() {
+      if (emitEvents) {
+        await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, query, ctx);
+        if (ctx.isCancelled) {
+          throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
+        }
       }
-    }
 
-    let qb = baseQuery().where(model.primaryKey, id);
-    
-    if (select && select.length > 0) {
-      qb = qb.select(select);
-    }
+      let qb = baseQuery().where(model.primaryKey, id);
 
-    const record = await qb.first();
+      if (select && select.length > 0) {
+        qb = qb.select(select);
+      }
 
-    if (!record) {
-      return null;
-    }
+      const record = await qb.first();
 
-    // Deserialize JSON fields
-    deserializeJsonFields(record, jsonColumns);
+      if (!record) {
+        return null;
+      }
 
-    // Load relations if requested
-    if (withs.length > 0) {
-      await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
-    }
+      deserializeJsonFields(record, jsonColumns);
 
-    // Emit afterFind
-    if (emitEvents) {
-      ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
-    }
+      if (withs.length > 0) {
+        await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
+      }
 
-    return record;
+      if (emitEvents) {
+        ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
+      }
+
+      return record;
+    }
+
+    if (cacheLayer && emitEvents && cacheLayer.strategyFor(model)) {
+      const strat = cacheLayer.strategyFor(model);
+      const kind = withs.length > 0 ? 'collection' : 'pk';
+      const fingerprint = cacheLayer.findByIdFingerprint(
+        model,
+        scopeContext,
+        id,
+        select || [],
+        withs
+      );
+      const tags = cacheLayer.buildReadTags(
+        model,
+        strat,
+        kind,
+        kind === 'pk' ? id : null
+      );
+      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
+    }
+
+    return loadFromDb();
   }
 
   /**
@@ -95,40 +115,65 @@ function createRepository(model, knex, initialContext) {
     const { with: withs = [], select } = options;
     const ctx = createEventContext(model.name, 'find');
 
-    // Emit beforeFind
-    await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, conditions, ctx);
-    if (ctx.isCancelled) {
-      throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
-    }
+    const condKeys = Object.keys(conditions);
+    const isPkOnly =
+      withs.length === 0 &&
+      condKeys.length === 1 &&
+      condKeys[0] === model.primaryKey;
 
-    let qb = baseQuery();
+    async function loadFromDb() {
+      await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, conditions, ctx);
+      if (ctx.isCancelled) {
+        throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
+      }
 
-    for (const [key, value] of Object.entries(conditions)) {
-      qb = qb.where(key, value);
-    }
+      let qb = baseQuery();
 
-    if (select && select.length > 0) {
-      qb = qb.select(select);
-    }
+      for (const [key, value] of Object.entries(conditions)) {
+        qb = qb.where(key, value);
+      }
 
-    const record = await qb.first();
+      if (select && select.length > 0) {
+        qb = qb.select(select);
+      }
 
-    if (!record) {
-      return null;
-    }
+      const record = await qb.first();
 
-    // Deserialize JSON fields
-    deserializeJsonFields(record, jsonColumns);
+      if (!record) {
+        return null;
+      }
 
-    // Load relations if requested
-    if (withs.length > 0) {
-      await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
-    }
+      deserializeJsonFields(record, jsonColumns);
 
-    // Emit afterFind
-    ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
+      if (withs.length > 0) {
+        await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
+      }
 
-    return record;
+      ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
+
+      return record;
+    }
+
+    if (cacheLayer && cacheLayer.strategyFor(model)) {
+      const strat = cacheLayer.strategyFor(model);
+      const kind = isPkOnly ? 'pk' : 'collection';
+      const fingerprint = cacheLayer.findOneFingerprint(
+        model,
+        scopeContext,
+        conditions,
+        select || [],
+        withs
+      );
+      const tags = cacheLayer.buildReadTags(
+        model,
+        strat,
+        kind,
+        kind === 'pk' ? conditions[model.primaryKey] : null
+      );
+      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
+    }
+
+    return loadFromDb();
   }
 
   /**
@@ -140,36 +185,43 @@ function createRepository(model, knex, initialContext) {
     const { with: withs = [], select } = options;
     const ctx = createEventContext(model.name, 'find');
 
-    // Emit beforeFind
-    await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, {}, ctx);
-    if (ctx.isCancelled) {
-      throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
-    }
+    async function loadFromDb() {
+      await ModelEvents.emitAsync(model.name, Hooks.BEFORE_FIND, {}, ctx);
+      if (ctx.isCancelled) {
+        throw new HookCancellationError(ctx.cancelReason, model.name, Hooks.BEFORE_FIND);
+      }
 
-    let qb = baseQuery();
+      let qb = baseQuery();
 
-    if (select && select.length > 0) {
-      qb = qb.select(select);
-    }
+      if (select && select.length > 0) {
+        qb = qb.select(select);
+      }
 
-    const records = await qb;
+      const records = await qb;
 
-    // Deserialize JSON fields
-    for (const record of records) {
-      deserializeJsonFields(record, jsonColumns);
-    }
+      for (const record of records) {
+        deserializeJsonFields(record, jsonColumns);
+      }
+
+      if (withs.length > 0 && records.length > 0) {
+        await loadRelations(records, ensureArray(withs), model, knex, scopeContext);
+      }
+
+      for (const record of records) {
+        ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
+      }
 
-    // Load relations if requested
-    if (withs.length > 0 && records.length > 0) {
-      await loadRelations(records, ensureArray(withs), model, knex, scopeContext);
+      return records;
     }
 
-    // Emit afterFind for each record
-    for (const record of records) {
-      ModelEvents.emit(model.name, Hooks.AFTER_FIND, record, ctx);
+    if (cacheLayer && cacheLayer.strategyFor(model)) {
+      const strat = cacheLayer.strategyFor(model);
+      const fingerprint = cacheLayer.findAllFingerprint(model, scopeContext, select || []);
+      const tags = cacheLayer.buildReadTags(model, strat, 'collection', null);
+      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, () => true);
     }
 
-    return records;
+    return loadFromDb();
   }
 
   /**
@@ -334,7 +386,11 @@ function createRepository(model, knex, initialContext) {
       qb = qb.where(key, value);
     }
 
-    return qb.update(updateData);
+    const updated = await qb.update(updateData);
+    if (cacheLayer && updated > 0) {
+      cacheLayer.invalidateModelAll(model);
+    }
+    return updated;
   }
 
   /**
@@ -391,6 +447,9 @@ function createRepository(model, knex, initialContext) {
     const deleted = await knex(model.table)
       .where(model.primaryKey, id)
       .delete();
+    if (cacheLayer && deleted > 0) {
+      cacheLayer.invalidateModelAll(model);
+    }
     return deleted > 0;
   }
 
@@ -445,7 +504,7 @@ function createRepository(model, knex, initialContext) {
    * @returns {import('./query-builder').QueryBuilder}
    */
   function query() {
-    return createQueryBuilder(model, knex, scopeContext);
+    return createQueryBuilder(model, knex, scopeContext, cacheLayer);
   }
 
   /**

package/core/orm/types.js

@@ -156,6 +156,7 @@
  * @property {AdminMetadata} [admin] - Admin panel metadata
  * @property {RestMetadata} [rest] - REST resource plugin metadata
  * @property {string[]} [hidden=[]] - Column names to never expose in API/templates (e.g. password_hash, api_token)
+ * @property {boolean|'auto'|'smart'|{strategy:'auto'|'smart'}} [cache] - Per-model query cache when DB cache is enabled (`true` uses DB defaultStrategy)
  */
 
 /**
@@ -170,6 +171,7 @@
  * @property {AdminMetadata} [admin] - Admin panel metadata
  * @property {RestMetadata} rest - REST resource plugin metadata
  * @property {string[]} hidden - Column names never exposed in API/templates
+ * @property {boolean|'auto'|'smart'|{strategy:'auto'|'smart'}|undefined} [cache] - Query cache strategy for this model
  */
 
 // ============================================================================
@@ -265,6 +267,15 @@
  * @property {string|Object} connection - Connection string or config object
  * @property {MigrationConfig} [migrations] - Migration configuration
  * @property {Object} [pool] - Connection pool settings
+ * @property {boolean|OrmDatabaseCacheConfig} [cache] - Enable ORM read cache (memory provider by default)
+ */
+
+/**
+ * @typedef {Object} OrmDatabaseCacheConfig
+ * @property {boolean} [enabled=true]
+ * @property {'auto'|'smart'} [defaultStrategy='auto'] - Default when model.cache is unspecified
+ * @property {import('./cache/types').CacheProvider} [provider] - Custom provider (e.g. Redis)
+ * @property {Object} [memory] - Options for built-in memory provider (maxEntries, defaultTtlMs)
  */
 
 /**
@@ -274,6 +285,16 @@
  * @property {function(function(TransactionContext): Promise): Promise} transaction - Run in transaction
  * @property {MigrationManager} migrate - Migration manager
  * @property {function(): Promise<void>} destroy - Close all connections
+ * @property {OrmCachePublicApi|null} [cache] - Cache controls when enabled
+ */
+
+/**
+ * @typedef {Object} OrmCachePublicApi
+ * @property {() => void} purge
+ * @property {(tags: string[]) => void} invalidateTags
+ * @property {(modelName: string) => void} invalidateModel
+ * @property {() => object} getMetrics
+ * @property {() => void} resetMetrics
  */
 
 /**

package/index.d.ts

@@ -6,6 +6,11 @@ import type { Application, NextFunction, Request, RequestHandler, Response } fro
 import type { Knex } from 'knex';
 import type { ZodObject, ZodTypeAny } from 'zod';
 
+/** Registered as createApp middlewares[name]: plain handler or (options) => handler (for middleware: ['name', options]). */
+export type WebspressoRegisteredMiddleware =
+  | RequestHandler
+  | ((options: unknown) => RequestHandler);
+
 // --- Express / app ---
 
 export interface ErrorPageContext {
@@ -23,7 +28,7 @@ export interface CreateAppOptions {
   publicDir?: string;
   logging?: boolean;
   helmet?: boolean | Record<string, unknown>;
-  middlewares?: Record<string, RequestHandler>;
+  middlewares?: Record<string, WebspressoRegisteredMiddleware>;
   plugins?: WebspressoPlugin[];
   assets?: {
     version?: string;
@@ -220,6 +225,7 @@ export interface ModelOptions {
   rest?: RestMetadata;
   hooks?: Record<string, (...args: unknown[]) => unknown>;
   hidden?: string[];
+  cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
 export interface ModelDefinition {
@@ -248,6 +254,7 @@ export interface ModelDefinition {
   };
   hidden: string[];
   hooks: Record<string, unknown>;
+  cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
 export function defineModel(options: ModelOptions): ModelDefinition;
@@ -343,6 +350,24 @@ export interface MigrationConfig {
   tableName?: string;
 }
 
+export interface OrmMemoryCacheOptions {
+  maxEntries?: number;
+  defaultTtlMs?: number;
+}
+
+export interface OrmDatabaseCacheConfig {
+  enabled?: boolean;
+  defaultStrategy?: 'auto' | 'smart';
+  provider?: {
+    get(key: string): unknown;
+    set(key: string, value: unknown, opts?: { tags?: string[]; ttlMs?: number }): void;
+    invalidateTags(tags: string[]): void;
+    clear(): void;
+    getSizeStats(): { entries: number; tags: number };
+  };
+  memory?: OrmMemoryCacheOptions;
+}
+
 export interface DatabaseConfig {
   client?: string;
   connection?: string | Record<string, unknown>;
@@ -350,9 +375,18 @@ export interface DatabaseConfig {
   migrations?: MigrationConfig;
   pool?: Record<string, unknown>;
   useNullAsDefault?: boolean;
+  cache?: boolean | OrmDatabaseCacheConfig;
   [key: string]: unknown;
 }
 
+export interface OrmCachePublicApi {
+  purge(): void;
+  invalidateTags(tags: string[]): void;
+  invalidateModel(modelName: string): void;
+  getMetrics(): Record<string, unknown>;
+  resetMetrics(): void;
+}
+
 export interface MigrationStatus {
   name: string;
   completed: boolean;
@@ -402,11 +436,20 @@ export interface DatabaseInstance {
   query(modelName: string, scopeContext?: ScopeContext): QueryBuilder;
   transaction<T>(callback: (ctx: TransactionContext) => Promise<T>): Promise<T>;
   createSeeder(): unknown;
+  cache: OrmCachePublicApi | null;
   destroy(): Promise<void>;
 }
 
 export function createDatabase(config: DatabaseConfig): DatabaseInstance;
 
+export function createMemoryCacheProvider(options?: OrmMemoryCacheOptions): {
+  get(key: string): unknown;
+  set(key: string, value: unknown, opts?: { tags?: string[]; ttlMs?: number }): void;
+  invalidateTags(tags: string[]): void;
+  clear(): void;
+  getSizeStats(): { entries: number; tags: number };
+};
+
 // --- ORM: nanoid / zod ---
 
 export function generateNanoid(options?: { maxLength?: number } | number): string;
@@ -480,3 +523,5 @@ export interface RestResourcePluginOptions {
 }
 
 export function restResourcePlugin(options?: RestResourcePluginOptions): WebspressoPlugin;
+
+export function ormCacheAdminPlugin(options: { db: DatabaseInstance }): WebspressoPlugin;

package/index.js

@@ -38,7 +38,7 @@ const {
 const orm = require('./core/orm');
 
 // Built-in plugins
-const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin, swaggerPlugin, healthCheckPlugin, restResourcePlugin } = require('./plugins');
+const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin, swaggerPlugin, healthCheckPlugin, restResourcePlugin, ormCacheAdminPlugin } = require('./plugins');
 
 module.exports = {
   // Main API
@@ -90,4 +90,5 @@ module.exports = {
   swaggerPlugin,
   healthCheckPlugin,
   restResourcePlugin,
+  ormCacheAdminPlugin,
 };

package/package.json

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

package/plugins/index.js

@@ -15,6 +15,7 @@ const recaptchaPlugin = require('./recaptcha');
 const swaggerPlugin = require('./swagger');
 const healthCheckPlugin = require('./health-check');
 const restResourcePlugin = require('./rest-resources');
+const ormCacheAdminPlugin = require('./orm-cache-admin');
 
 module.exports = {
   sitemapPlugin,
@@ -29,5 +30,6 @@ module.exports = {
   swaggerPlugin,
   healthCheckPlugin,
   restResourcePlugin,
+  ormCacheAdminPlugin,
 };
 

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

@@ -0,0 +1,146 @@
+/**
+ * Admin SPA page for ORM cache (Mithril string component)
+ * @module plugins/orm-cache-admin/admin-component
+ */
+
+function generateOrmCacheAdminComponent() {
+  return `
+(function() {
+
+function ormCacheApi(method, path, body) {
+  var opts = { method: method, credentials: 'same-origin' };
+  if (body !== undefined) {
+    opts.headers = { 'Content-Type': 'application/json' };
+    opts.body = JSON.stringify(body);
+  }
+  return fetch('/_admin/api/orm-cache' + path, opts).then(function(r) {
+    return r.json().then(function(j) {
+      if (!r.ok) throw new Error(j.error || r.statusText);
+      return j;
+    });
+  });
+}
+
+var OrmCachePage = {
+  oninit: function(vnode) {
+    vnode.state.loading = true;
+    vnode.state.error = null;
+    vnode.state.stats = null;
+    vnode.state.modelName = '';
+    this.refresh(vnode);
+  },
+  refresh: function(vnode) {
+    vnode.state.loading = true;
+    vnode.state.error = null;
+    ormCacheApi('get', '/stats').then(function(s) {
+      vnode.state.stats = s;
+      vnode.state.loading = false;
+      m.redraw();
+    }).catch(function(e) {
+      vnode.state.error = e.message || String(e);
+      vnode.state.loading = false;
+      m.redraw();
+    });
+  },
+  purge: function(vnode) {
+    if (!confirm('Purge entire ORM cache?')) return;
+    ormCacheApi('post', '/purge').then(function() {
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  invalidateModel: function(vnode) {
+    var name = (vnode.state.modelName || '').trim();
+    if (!name) return;
+    ormCacheApi('post', '/invalidate', { model: name }).then(function() {
+      vnode.state.modelName = '';
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  resetMetrics: function(vnode) {
+    ormCacheApi('post', '/metrics/reset').then(function() {
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  view: function(vnode) {
+    var s = vnode.state;
+    var self = this;
+    return m(Layout, [
+      m(Breadcrumb, { items: [{ label: 'ORM Cache', href: '/orm-cache' }] }),
+      m('div.mb-6', [
+        m('h1.text-2xl.font-bold.text-gray-900', 'ORM query cache'),
+        m('p.text-gray-500.text-sm.mt-1', 'Hit/miss metrics and manual invalidation (memory provider)'),
+      ]),
+      s.loading
+        ? m('div.flex.justify-center.py-16', m(Spinner))
+        : s.error
+          ? m('div.bg-red-50.text-red-700.p-4.rounded-lg', s.error)
+          : m('div.space-y-6', [
+              m('div.grid.grid-cols-2.md:grid-cols-4.gap-4', [
+                statBox('Hits', s.stats && s.stats.hits),
+                statBox('Misses', s.stats && s.stats.misses),
+                statBox('Hit rate', formatRate(s.stats && s.stats.hitRate)),
+                statBox('Bypassed', s.stats && s.stats.bypassed),
+              ]),
+              m('div.grid.grid-cols-2.md:grid-cols-4.gap-4', [
+                statBox('Sets', s.stats && s.stats.sets),
+                statBox('Invalidations', s.stats && s.stats.invalidations),
+                statBox('Approx keys', s.stats && s.stats.approxKeys),
+                statBox('Approx tags', s.stats && s.stats.approxTags),
+              ]),
+              m('div.flex.flex-wrap.gap-2', [
+                m('button.px-4.py-2.bg-red-600.text-white.rounded-md.text-sm', {
+                  onclick: function() { self.purge(vnode); },
+                }, 'Purge all'),
+                m('button.px-4.py-2.bg-gray-200.text-gray-800.rounded-md.text-sm', {
+                  onclick: function() { self.resetMetrics(vnode); },
+                }, 'Reset metrics'),
+                m('button.px-4.py-2.bg-blue-600.text-white.rounded-md.text-sm', {
+                  onclick: function() { self.refresh(vnode); },
+                }, 'Refresh'),
+              ]),
+              m('div.bg-white.rounded-lg.shadow.p-4', [
+                m('h3.text-sm.font-semibold.mb-2', 'Invalidate by model'),
+                m('div.flex.gap-2', [
+                  m('input.flex-1.border.rounded.px-3.py-2.text-sm', {
+                    placeholder: 'Model name (e.g. User)',
+                    value: s.modelName,
+                    oninput: function(e) { s.modelName = e.target.value; },
+                  }),
+                  m('button.px-4.py-2.bg-amber-600.text-white.rounded-md.text-sm', {
+                    onclick: function() { self.invalidateModel(vnode); },
+                  }, 'Invalidate'),
+                ]),
+              ]),
+            ]),
+    ]);
+  },
+};
+
+function statBox(label, value) {
+  return m('div.bg-white.rounded-lg.shadow.p-4', [
+    m('p.text-xs.text-gray-500.uppercase', label),
+    m('p.text-xl.font-semibold.text-gray-900', value === undefined || value === null ? '—' : String(value)),
+  ]);
+}
+
+function formatRate(r) {
+  if (r === null || r === undefined || isNaN(r)) return '—';
+  return (r * 100).toFixed(1) + '%';
+}
+
+window.__customPages = window.__customPages || {};
+window.__customPages['orm-cache'] = OrmCachePage;
+})();
+`;
+}
+
+module.exports = { generateOrmCacheAdminComponent };