webspresso 0.0.64 → 0.0.66

package/README.md

@@ -15,7 +15,8 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Lifecycle Hooks**: Global and route-level hooks for request processing
 - **Template Helpers**: Laravel-inspired helper functions available in templates
 - **Plugin System**: Extensible architecture with version control and inter-plugin communication
-- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models
+- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models, optional admin UI for ORM query cache metrics and purge
+- **Session authentication** (optional): `createAuth` / `quickAuth` in **`webspresso/core/auth`** — pass the manager to **`createApp({ auth })`** for `express-session`, `req.user` / `req.auth`, remember-me tokens, and policy-style authorization. Full walkthrough: **[`doc/index.html#authentication`](doc/index.html#authentication)**.
 - **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
 
 ## Installation
@@ -356,6 +357,8 @@ Creates and configures the Express app.
   - `false`: Disable Helmet
   - `Object`: Custom Helmet configuration (merged with defaults)
 - `middlewares` (optional): Named middleware registry for routes
+- `auth` (optional): `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`require('webspresso/core/auth')`). Registers session + cookie parsing, attaches **`req.auth`** / **`req.user`**, and injects named route middleware **`auth`** and **`guest`** (do not reuse those names for custom handlers if you pass `auth`). See **[`doc/index.html#authentication`](doc/index.html#authentication)**.
+- `setupRoutes(app, ctx)` (optional): Register custom Express routes after file routes and plugin `onRoutesReady`, before the 404 handler — use for login/logout handlers when using the auth module; **`ctx.authMiddleware`** exposes `requireAuth`, `requireGuest`, etc.
 
 **Example with middlewares:**
 
@@ -399,6 +402,27 @@ module.exports = {
 };
 ```
 
+**Parameterized named middleware:** entries in `middlewares` can be **factories** `(options) => (req, res, next) => …`. A bare string calls the factory with `{}`; a **tuple** passes options:
+
+```javascript
+// pages/api/account.get.js
+module.exports = {
+  middleware: [['auth', { api: true }], 'rateLimit'], // JSON 401 instead of redirect when using createApp({ auth })
+  handler: (req, res) => res.json({ ok: true }),
+};
+
+// server.js — custom factory
+middlewares: {
+  oauth: (opts) => (req, res, next) => {
+    if (opts.google && !req.headers['x-google']) return res.status(401).end();
+    next();
+  },
+};
+// pages/example/index.js → middleware: [['oauth', { google: true }], 'auth']
+```
+
+Plain `(req, res, next) => …` handlers still work as today. Tuple form **requires** a factory for that name (you get a clear error if you mix a plain handler with `['name', opts]`).
+
 ### 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:
@@ -549,7 +573,15 @@ Works with Vite and Webpack manifest formats:
 }
 ```
 
-**Returns:** `{ app, nunjucksEnv, pluginManager }`
+**Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is `null` when `auth` was not passed.
+
+### Authentication (session)
+
+Optional **session-based** auth lives under **`webspresso/core/auth`**: **`createAuth`**, **`quickAuth`**, **`hash`** / **`verify`**, **`setupAuthMiddleware`**, **`createRememberTokensTable`**, and policy helpers. Pass the manager to **`createApp({ auth })`** so routes can use **`middleware: ['auth']`** or **`['guest']`** and handlers can call **`req.auth.attempt()`**, **`req.auth.logout()`**, **`req.auth.can()`**, etc.
+
+The **admin panel** plugin uses its **own** session and `/api/auth/*` routes (`req.session.adminUser`) — it is separate from **`createApp({ auth })`**.
+
+For integration patterns (remember-me table, `setupRoutes`, file-router ordering), see **[`doc/index.html#authentication`](doc/index.html#authentication)**.
 
 ## Plugin System
 
@@ -838,6 +870,23 @@ const { app } = createApp({
 
 Programmatic API (other plugins): `ctx.usePlugin('audit-log')` exposes `queryLogs`, `purgeAuditLogs`, and `getMigrationTemplate()`.
 
+**ORM cache admin plugin:**
+- Depends on **`adminPanelPlugin`** and a database instance created with **`createDatabase({ cache: true | { … } })`** so **`db.cache`** is non-null
+- Registers an **ORM Cache** admin page (metrics, full purge, per-model invalidation, reset counters) backed by **`db.cache`**
+- If `db.cache` is disabled, the plugin logs a warning and skips registration
+
+```javascript
+const { adminPanelPlugin, ormCacheAdminPlugin } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [
+    adminPanelPlugin({ db }),
+    ormCacheAdminPlugin({ db }),
+  ],
+});
+```
+
 **reCAPTCHA plugin:**
 - Google reCAPTCHA **v2** (checkbox) or **v3** (score): server verification via `https://www.google.com/recaptcha/api/siteverify` (no extra npm dependency; Node 18+ `fetch`)
 - Registers CSP entries for Google scripts/iframes; Nunjucks helpers: `recaptchaScript`, `recaptchaWidget` (v2), `recaptchaV3Token` (hidden input + execute for v3 — use with `version: 'v3'` and `recaptchaScript` loads `api.js?render=siteKey`)
@@ -1562,6 +1611,52 @@ await db.transaction(async (trx) => {
 });
 ```
 
+**ORM reads inside `db.transaction()` always bypass the query cache** (Knex transaction client), so you never serve stale rows mid-transaction.
+
+### ORM query cache (optional)
+
+Enable an in-process, tag-based cache for common read paths. Default provider is in-memory (`createMemoryCacheProvider`); you can pass a custom **`provider`** with the same shape (`get`, `set` with optional `tags` / `ttlMs`, `invalidateTags`, `clear`, `getSizeStats`).
+
+**Turn it on:**
+
+```javascript
+const db = createDatabase({
+  client: 'pg',
+  connection: process.env.DATABASE_URL,
+  models: './models',
+  cache: true, // same as { enabled: true, defaultStrategy: 'auto', memory provider }
+  // cache: {
+  //   enabled: true,
+  //   defaultStrategy: 'auto', // or 'smart'
+  //   memory: { maxEntries: 50_000, defaultTtlMs: undefined },
+  //   // provider: myRedisLikeAdapter,
+  // },
+});
+```
+
+When enabled, **`db.cache`** exposes **`purge()`**, **`invalidateTags(string[])`**, **`invalidateModel('ModelName')`**, **`getMetrics()`**, and **`resetMetrics()`**. When the cache is off, **`db.cache`** is **`null`**.
+
+**Per-model opt-in / strategy** (inherits the database **`defaultStrategy`** when set to `true`):
+
+```javascript
+defineModel({
+  name: 'User',
+  table: 'users',
+  schema: UserSchema,
+  cache: true,              // use db defaultStrategy
+  // cache: 'auto', // invalidate all cached reads for this model on any row change
+  // cache: 'smart', // finer-grained tags: PK reads vs list/collection queries
+  // cache: { strategy: 'smart' },
+  // cache: false,         // never cache this model
+});
+```
+
+**What gets cached:** **`findById`**, **`findOne`**, **`findAll`**, and query builder **`first`**, **`list`**, **`count`**, **`paginate`** — only when the model participates in caching and the read is not on a transaction connection. Some query shapes are never cached (e.g. raw `where` fragments); the layer increments a **`bypassed`** metric for those.
+
+**Invalidation:** Hooks on **`afterCreate`**, **`afterUpdate`**, **`afterDelete`**, and **`afterRestore`** schedule tag invalidation after the Knex transaction commits (when applicable). With **`auto`**, every mutation clears all cache entries tagged for that model. With **`smart`**, creates invalidate collection query tags; updates/deletes target the row’s primary key tag plus collection tags when the record exposes an id (falls back to full-model invalidation if the id is missing). Bulk **`updateWhere`** / query-builder **`update`** / **`delete`** that affect rows call **`invalidateModelAll`** for safety.
+
+**Exports:** **`createMemoryCacheProvider`**, **`OrmCacheLayer`**, and **`createOrmCacheFromConfig`** are available from **`webspresso`** for advanced/testing setups.
+
 ### Migrations
 
 **CLI Commands:**

package/core/auth/middleware.js

@@ -223,9 +223,9 @@ function createAuthMiddleware(authManager) {
     // Utility
     parseMiddlewareString,
     
-    // Aliases for route config
-    auth: requireAuth(),
-    guest: requireGuest(),
+    // Aliases for route config (factories — file-router calls requireAuth(opts) / requireGuest(opts))
+    auth: requireAuth,
+    guest: requireGuest,
   };
 }
 

package/core/orm/cache/fingerprint.js

@@ -0,0 +1,73 @@
+/**
+ * Stable cache key fingerprint for ORM reads
+ * @module core/orm/cache/fingerprint
+ */
+
+const crypto = require('crypto');
+
+/**
+ * @param {*} v
+ * @returns {*}
+ */
+function stableValue(v) {
+  if (v === null || v === undefined) return v;
+  if (typeof v !== 'object') return v;
+  if (Array.isArray(v)) return v.map(stableValue);
+  const keys = Object.keys(v).sort();
+  const out = {};
+  for (const k of keys) out[k] = stableValue(v[k]);
+  return out;
+}
+
+/**
+ * @param {import('../types').ScopeContext} scopeContext
+ */
+function scopeFingerprint(scopeContext) {
+  return {
+    tenantId: scopeContext.tenantId,
+    withTrashed: !!scopeContext.withTrashed,
+    onlyTrashed: !!scopeContext.onlyTrashed,
+  };
+}
+
+/**
+ * @param {import('../types').QueryState} state
+ */
+function serializeWheres(wheres) {
+  return wheres.map((w) => {
+    if (w.raw) {
+      return { raw: true, sql: w.sql, bindings: w.bindings, boolean: w.boolean };
+    }
+    return {
+      column: w.column,
+      operator: w.operator,
+      value: w.value,
+      boolean: w.boolean,
+    };
+  });
+}
+
+/**
+ * @param {import('../model').ModelDefinition} model
+ * @param {import('../types').ScopeContext} scopeContext
+ * @param {object} parts
+ * @returns {string} hex key
+ */
+function hashKey(model, scopeContext, parts) {
+  const payload = stableValue({
+    model: model.name,
+    table: model.table,
+    pk: model.primaryKey,
+    scope: scopeFingerprint(scopeContext),
+    ...parts,
+  });
+  const json = JSON.stringify(payload);
+  return crypto.createHash('sha256').update(json).digest('hex').slice(0, 40);
+}
+
+module.exports = {
+  stableValue,
+  scopeFingerprint,
+  serializeWheres,
+  hashKey,
+};

package/core/orm/cache/index.js

@@ -0,0 +1,73 @@
+/**
+ * ORM query cache (memory provider + tag invalidation)
+ * @module core/orm/cache
+ */
+
+const { createMemoryCacheProvider } = require('./memory-provider');
+const { OrmCacheLayer } = require('./layer');
+const { registerOrmCacheListeners, unregisterOrmCacheListeners } = require('./listeners');
+
+/**
+ * @param {boolean|object} cacheConfig - true | { enabled, defaultStrategy, provider, memory }
+ * @returns {{ layer: OrmCacheLayer|null, publicApi: object|null }}
+ */
+function createOrmCacheFromConfig(cacheConfig) {
+  const normalized = normalizeCacheConfig(cacheConfig);
+  if (!normalized) {
+    return { layer: null, publicApi: null };
+  }
+
+  const provider =
+    normalized.provider || createMemoryCacheProvider(normalized.memory || {});
+
+  const layer = new OrmCacheLayer(provider, {
+    defaultStrategy: normalized.defaultStrategy,
+    providerKind: normalized.provider ? 'custom' : 'memory',
+  });
+
+  registerOrmCacheListeners(layer);
+
+  const publicApi = {
+    purge: () => layer.purge(),
+    invalidateTags: (tags) => layer.invalidateTags(tags),
+    invalidateModel: (modelName) => {
+      const { getModel } = require('../model');
+      const model = getModel(modelName);
+      if (model) layer.invalidateModelAll(model);
+    },
+    getMetrics: () => ({
+      ...layer.getMetrics(),
+      providerKind: layer.providerKind || 'memory',
+    }),
+    resetMetrics: () => layer.resetMetrics(),
+  };
+
+  return { layer, publicApi };
+}
+
+/**
+ * @param {boolean|object|undefined} cacheConfig
+ */
+function normalizeCacheConfig(cacheConfig) {
+  if (cacheConfig === true) {
+    return { enabled: true, defaultStrategy: 'auto', provider: null, memory: {} };
+  }
+  if (!cacheConfig || cacheConfig.enabled === false) {
+    return null;
+  }
+  return {
+    enabled: true,
+    defaultStrategy: cacheConfig.defaultStrategy === 'smart' ? 'smart' : 'auto',
+    provider: cacheConfig.provider || null,
+    memory: cacheConfig.memory || {},
+  };
+}
+
+module.exports = {
+  createOrmCacheFromConfig,
+  normalizeCacheConfig,
+  createMemoryCacheProvider,
+  OrmCacheLayer,
+  registerOrmCacheListeners,
+  unregisterOrmCacheListeners,
+};

package/core/orm/cache/layer.js

@@ -0,0 +1,314 @@
+/**
+ * ORM cache orchestration: metrics, strategy, read wrapper, invalidation helpers
+ * @module core/orm/cache/layer
+ */
+
+const { hashKey, serializeWheres } = require('./fingerprint');
+
+/**
+ * @param {*} knex
+ */
+function isTransactionKnex(knex) {
+  return !!(knex && knex.isTransaction);
+}
+
+/**
+ * @param {import('../model').ModelDefinition} model
+ * @returns {'auto'|'smart'|null}
+ */
+function modelCacheStrategy(model, defaultStrategy) {
+  const c = model.cache;
+  if (c === false || c === undefined || c === null) return null;
+  if (c === true) return defaultStrategy;
+  if (c === 'auto' || c === 'smart') return c;
+  if (typeof c === 'object' && c.strategy) {
+    return c.strategy === 'smart' ? 'smart' : 'auto';
+  }
+  return defaultStrategy;
+}
+
+function cloneForCache(value) {
+  if (value === undefined) return undefined;
+  if (typeof structuredClone === 'function') return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+}
+
+class OrmCacheLayer {
+  /**
+   * @param {import('./types').CacheProvider} provider
+   * @param {object} [options]
+   * @param {'auto'|'smart'} [options.defaultStrategy='auto']
+   */
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.providerKind = options.providerKind || 'memory';
+    this.defaultStrategy = options.defaultStrategy || 'auto';
+    this.metrics = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      invalidations: 0,
+      bypassed: 0,
+    };
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   */
+  strategyFor(model) {
+    return modelCacheStrategy(model, this.defaultStrategy);
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {*} knex
+   */
+  shouldBypassRead(model, knex) {
+    if (!this.provider) return true;
+    if (!this.strategyFor(model)) return true;
+    if (isTransactionKnex(knex)) return true;
+    return false;
+  }
+
+  resetMetrics() {
+    this.metrics.hits = 0;
+    this.metrics.misses = 0;
+    this.metrics.sets = 0;
+    this.metrics.invalidations = 0;
+    this.metrics.bypassed = 0;
+  }
+
+  getMetrics() {
+    const { entries, tags } = this.provider.getSizeStats();
+    const { hits, misses, sets, invalidations, bypassed } = this.metrics;
+    const lookups = hits + misses;
+    const hitRate = lookups > 0 ? hits / lookups : null;
+    return {
+      hits,
+      misses,
+      sets,
+      invalidations,
+      bypassed,
+      hitRate,
+      approxKeys: entries,
+      approxTags: tags,
+      enabled: true,
+      providerKind: this.providerKind,
+    };
+  }
+
+  invalidateTags(tags) {
+    const uniq = [...new Set(tags.filter(Boolean))];
+    if (uniq.length === 0) return;
+    this.provider.invalidateTags(uniq);
+    this.metrics.invalidations += 1;
+  }
+
+  purge() {
+    this.provider.clear();
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string} fingerprintKey
+   * @param {string[]} tags
+   * @param {() => Promise<*>} executor
+   * @param {(*)=>boolean} [shouldCache]
+   */
+  async wrapRead(model, knex, scopeContext, fingerprintKey, tags, executor, shouldCache = () => true) {
+    if (this.shouldBypassRead(model, knex)) {
+      this.metrics.bypassed += 1;
+      return executor();
+    }
+
+    const cached = this.provider.get(fingerprintKey);
+    if (cached !== undefined) {
+      this.metrics.hits += 1;
+      return cloneForCache(cached);
+    }
+
+    this.metrics.misses += 1;
+    const result = await executor();
+
+    if (shouldCache(result)) {
+      this.provider.set(fingerprintKey, cloneForCache(result), { tags });
+      this.metrics.sets += 1;
+    }
+
+    return result;
+  }
+
+  /**
+   * Deferred invalidation after Knex transaction commit
+   * @param {*} ctxTrx - createEventContext trx
+   * @param {string[]} tags
+   */
+  scheduleInvalidate(ctxTrx, tags) {
+    const uniq = [...new Set(tags.filter(Boolean))];
+    if (uniq.length === 0) return;
+
+    if (!ctxTrx) {
+      this.invalidateTags(uniq);
+      return;
+    }
+
+    const p = ctxTrx.executionPromise;
+    if (p && typeof p.then === 'function') {
+      p.then(() => {
+        this.invalidateTags(uniq);
+      }).catch(() => {});
+    } else {
+      this.invalidateTags(uniq);
+    }
+  }
+
+  /**
+   * Build tags for a read operation
+   * @param {import('../model').ModelDefinition} model
+   * @param {'auto'|'smart'} strategy
+   * @param {'pk'|'collection'} kind
+   * @param {string|number|null} [pkValue]
+   */
+  buildReadTags(model, strategy, kind, pkValue) {
+    const base = [`model:${model.name}`, `table:${model.table}`];
+    if (strategy === 'auto') return base;
+    if (kind === 'pk' && pkValue != null) {
+      return [...base, `pk:${model.name}:${pkValue}`];
+    }
+    return [...base, `q:${model.name}`];
+  }
+
+  /**
+   * Classify query builder state for smart caching
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').QueryState} state
+   * @param {'first'|'list'|'count'|'paginate'} op
+   */
+  classifyQueryBuilder(model, state, op) {
+    const hasRaw = state.wheres.some((w) => w.raw);
+    if (hasRaw) return { cacheable: false, kind: 'collection' };
+
+    if (state.withs.length > 0) return { cacheable: true, kind: 'collection' };
+
+    if (op === 'count' || op === 'paginate' || op === 'list') {
+      return { cacheable: true, kind: 'collection' };
+    }
+
+    // first()
+    if (state.wheres.length !== 1) return { cacheable: true, kind: 'collection' };
+
+    const w = state.wheres[0];
+    if (w.raw || w.boolean === 'or') return { cacheable: true, kind: 'collection' };
+    if (w.column !== model.primaryKey || w.operator !== '=') {
+      return { cacheable: true, kind: 'collection' };
+    }
+
+    return { cacheable: true, kind: 'pk', pkValue: w.value };
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {import('../types').QueryState} state
+   * @param {'first'|'list'|'count'|'paginate'} op
+   * @param {object} [extra] e.g. { page, perPage } for paginate
+   */
+  queryBuilderFingerprint(model, scopeContext, state, op, extra = {}) {
+    return hashKey(model, scopeContext, {
+      op,
+      selects: [...state.selects].sort(),
+      wheres: serializeWheres(state.wheres),
+      orderBys: state.orderBys,
+      limit: state.limitValue,
+      offset: state.offsetValue,
+      withs: [...state.withs].sort(),
+      extra,
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string|number} id
+   * @param {string[]} [select]
+   * @param {string[]} [withs]
+   */
+  findByIdFingerprint(model, scopeContext, id, select = [], withs = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findById',
+      id: String(id),
+      select: [...select].sort(),
+      withs: [...withs].sort(),
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {Record<string, *>} conditions
+   * @param {string[]} [select]
+   * @param {string[]} [withs]
+   */
+  findOneFingerprint(model, scopeContext, conditions, select = [], withs = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findOne',
+      conditions: Object.keys(conditions)
+        .sort()
+        .reduce((acc, k) => {
+          acc[k] = conditions[k];
+          return acc;
+        }, {}),
+      select: [...select].sort(),
+      withs: [...withs].sort(),
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string[]} [select]
+   */
+  findAllFingerprint(model, scopeContext, select = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findAll',
+      select: [...select].sort(),
+    });
+  }
+
+  /**
+   * Conservative invalidation for a model (auto-equivalent)
+   * @param {import('../model').ModelDefinition} model
+   */
+  invalidateModelAll(model) {
+    this.invalidateTags([`model:${model.name}`, `table:${model.table}`]);
+  }
+
+  /**
+   * Smart / auto write tags
+   * @param {import('../model').ModelDefinition} model
+   * @param {'auto'|'smart'} strategy
+   * @param {'create'|'update'|'delete'|'restore'} op
+   * @param {*} [record] for pk
+   */
+  tagsForMutation(model, strategy, op, record) {
+    const name = model.name;
+    const table = model.table;
+    if (strategy === 'auto') {
+      return [`model:${name}`, `table:${table}`];
+    }
+    // smart: avoid invalidating `model:` / `table:` on every row write (would flush all PK rows)
+    if (op === 'create') {
+      return [`q:${name}`];
+    }
+    const id = record && record[model.primaryKey];
+    if (id == null) return [`model:${name}`, `table:${table}`];
+    return [`pk:${name}:${id}`, `q:${name}`];
+  }
+}
+
+module.exports = {
+  OrmCacheLayer,
+  modelCacheStrategy,
+  isTransactionKnex,
+};

package/core/orm/cache/listeners.js

@@ -0,0 +1,67 @@
+/**
+ * Wire ModelEvents to ORM cache invalidation
+ * Supports multiple DB/cache layers (e.g. tests); each layer receives mutation events.
+ * @module core/orm/cache/listeners
+ */
+
+const { ModelEvents, Hooks } = require('../events');
+const { getModel } = require('../model');
+
+/** @type {Set<import('./layer').OrmCacheLayer>} */
+const layers = new Set();
+let hooked = false;
+
+/**
+ * @param {import('./layer').OrmCacheLayer} cacheLayer
+ */
+function registerOrmCacheListeners(cacheLayer) {
+  layers.add(cacheLayer);
+  if (hooked) return;
+  hooked = true;
+
+  /**
+   * @param {*} record
+   * @param {import('../events').EventContext} ctx
+   * @param {'create'|'update'|'delete'|'restore'} op
+   */
+  function handleMutation(record, ctx, op) {
+    const modelName = ctx.model;
+    const model = getModel(modelName);
+    if (!model) return;
+
+    for (const layer of layers) {
+      if (!layer.strategyFor(model)) continue;
+      const strat = layer.strategyFor(model);
+      const tags = layer.tagsForMutation(model, strat, op, record);
+      layer.scheduleInvalidate(ctx.trx, tags);
+    }
+  }
+
+  ModelEvents.on(`*.${Hooks.AFTER_CREATE}`, (record, ctx) => {
+    handleMutation(record, ctx, 'create');
+  });
+
+  ModelEvents.on(`*.${Hooks.AFTER_UPDATE}`, (record, ctx) => {
+    handleMutation(record, ctx, 'update');
+  });
+
+  ModelEvents.on(`*.${Hooks.AFTER_DELETE}`, (record, ctx) => {
+    handleMutation(record, ctx, 'delete');
+  });
+
+  ModelEvents.on(`*.${Hooks.AFTER_RESTORE}`, (record, ctx) => {
+    handleMutation(record, ctx, 'restore');
+  });
+}
+
+/**
+ * @param {import('./layer').OrmCacheLayer} cacheLayer
+ */
+function unregisterOrmCacheListeners(cacheLayer) {
+  layers.delete(cacheLayer);
+}
+
+module.exports = {
+  registerOrmCacheListeners,
+  unregisterOrmCacheListeners,
+};