webspresso 0.0.65 → 0.0.67

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;
@@ -40,6 +45,11 @@ export interface CreateAppOptions {
   timeout?: string | false;
   auth?: unknown;
   db?: DatabaseInstance | null;
+  /** Opt-in Alpine / swup assets under `/__webspresso/client-runtime/*`. Env: WEBSPRESSO_ALPINE, WEBSPRESSO_SWUP. */
+  clientRuntime?: {
+    alpine?: boolean | Record<string, unknown>;
+    swup?: boolean | Record<string, unknown>;
+  };
   setupRoutes?: (app: Application, ctx: SetupRoutesContext) => void;
   [key: string]: unknown;
 }
@@ -49,6 +59,7 @@ export interface SetupRoutesContext {
   authMiddleware?: RequestHandler;
   pluginManager: PluginManager;
   options: CreateAppOptions;
+  clientRuntime: { alpine: boolean; swup: boolean };
 }
 
 export interface CreateAppResult {
@@ -220,6 +231,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 +260,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 +356,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 +381,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 +442,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 +529,5 @@ export interface RestResourcePluginOptions {
 }
 
 export function restResourcePlugin(options?: RestResourcePluginOptions): WebspressoPlugin;
+
+export function ormCacheAdminPlugin(options: { db: DatabaseInstance }): WebspressoPlugin;

package/index.js

@@ -3,6 +3,8 @@
  */
 
 const { createApp } = require('./src/server');
+const { resolveClientRuntime } = require('./src/client-runtime/resolve');
+const { CLIENT_RUNTIME_BASE } = require('./src/client-runtime/mount');
 const {
   attachDbMiddleware,
   getAppContext,
@@ -38,11 +40,13 @@ 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
   createApp,
+  resolveClientRuntime,
+  CLIENT_RUNTIME_BASE,
 
   attachDbMiddleware,
   getAppContext,
@@ -90,4 +94,5 @@ module.exports = {
   swaggerPlugin,
   healthCheckPlugin,
   restResourcePlugin,
+  ormCacheAdminPlugin,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "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",
@@ -42,9 +42,13 @@
     "utils/",
     "core/",
     "plugins/",
-    "templates/"
+    "templates/",
+    "views/partials/webspresso-client-runtime.njk"
   ],
   "dependencies": {
+    "@swup/head-plugin": "^2.3.1",
+    "@swup/scripts-plugin": "^2.1.0",
+    "alpinejs": "^3.15.11",
     "bcrypt": "^5.1.1",
     "commander": "^11.1.0",
     "connect-timeout": "^1.9.1",
@@ -57,6 +61,7 @@
     "knex": "^3.1.0",
     "nunjucks": "^3.2.4",
     "sharp": "^0.33.5",
+    "swup": "^4.8.3",
     "zod": "^3.23.0",
     "zod-to-json-schema": "^3.25.2"
   },
@@ -85,10 +90,10 @@
     }
   },
   "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.14.0",
     "@faker-js/faker": "^9.9.0",
     "@playwright/test": "^1.48.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.0.0",
     "better-sqlite3": "^11.10.0",
     "chokidar": "^3.5.3",

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,
 };