domma-cms 0.17.0 → 0.18.0

package/server/services/cache/index.js

@@ -0,0 +1,229 @@
+import {MemoryDriver} from './drivers/MemoryDriver.js';
+import {NoneDriver} from './drivers/NoneDriver.js';
+
+const KEY_VERSION = 'v1:';
+
+let _driver = new NoneDriver();
+let _enabled = false;
+let _lastConfig = null;
+/** @type {Map<string, Promise<*>>} */
+const _inflight = new Map();
+
+const _stats = {
+    hits: 0,
+    misses: 0,
+    writes: 0,
+    invalidations: 0,
+    lastClearedAt: null,
+    lastInvalidationAt: null,
+    initialisedAt: null
+};
+
+/**
+ * @param {{
+ *   enabled?: boolean,
+ *   driver?: 'memory' | 'none' | 'redis',
+ *   memory?: {maxItems?: number, defaultTtlSeconds?: number},
+ *   redis?: {url: string, keyPrefix?: string}
+ * }} config
+ */
+export async function initCache(config = {}) {
+    _lastConfig = {...config};
+    _stats.initialisedAt = new Date().toISOString();
+    if (config.enabled === false) {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    const name = config.driver ?? 'memory';
+    if (name === 'memory') {
+        _driver = new MemoryDriver(config.memory ?? {});
+        _enabled = true;
+        return;
+    }
+    if (name === 'none') {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    if (name === 'redis') {
+        const {RedisDriver} = await import('./drivers/RedisDriver.js');
+        _driver = new RedisDriver(config.redis ?? {});
+        await _driver.connect();
+        _enabled = true;
+        return;
+    }
+    throw new Error(`Unknown cache driver: ${name}`);
+}
+
+/**
+ * Flip the cache on or off at runtime.
+ *
+ * When turning on, re-initialise with the last config (or sensible defaults)
+ * so a previously disabled cache gets a real driver. When turning off, keep
+ * the driver in place but short-circuit reads/writes — preserves cached data
+ * if the user toggles back on. The persistence of this choice across restarts
+ * is the caller's responsibility (the route handler writes to config/cache.json).
+ */
+export async function setEnabled(enabled) {
+    if (Boolean(enabled) === _enabled) return;
+    if (enabled) {
+        if (_driver instanceof NoneDriver) {
+            // No usable driver yet — bootstrap one from last-known config.
+            const cfg = {...(_lastConfig || {}), enabled: true};
+            if (!cfg.driver || cfg.driver === 'none') cfg.driver = 'memory';
+            await initCache(cfg);
+        } else {
+            // Memory/Redis driver still live — flip the flag and preserve data.
+            _enabled = true;
+        }
+    } else {
+        _enabled = false;
+        _inflight.clear();
+    }
+}
+
+export function isEnabled() {
+    return _enabled;
+}
+
+export async function get(key) {
+    return _driver.get(_vk(key));
+}
+
+export async function set(key, value, opts = {}) {
+    return _driver.set(_vk(key), value, opts);
+}
+
+export async function invalidateTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0) return;
+    _stats.invalidations++;
+    _stats.lastInvalidationAt = new Date().toISOString();
+    return _driver.invalidateTags(tags);
+}
+
+export async function clear() {
+    _inflight.clear();
+    _stats.lastClearedAt = new Date().toISOString();
+    return _driver.clear();
+}
+
+/**
+ * List the cache's keys with their tags and expiry. Values are deliberately
+ * excluded — cached entries can be megabytes of HTML.
+ * @returns {{key: string, tags: string[], expiresAt: number|null}[]}
+ */
+export function listEntries() {
+    if (typeof _driver.listEntries !== 'function') return [];
+    return _driver.listEntries().map(e => ({
+        ...e,
+        // Strip the internal v1: version prefix for display.
+        key: e.key.startsWith(KEY_VERSION) ? e.key.slice(KEY_VERSION.length) : e.key
+    }));
+}
+
+/**
+ * Snapshot of cache health for the dashboard widget.
+ * Counts are process-lifetime; restart resets them.
+ */
+export function getStats() {
+    const total = _stats.hits + _stats.misses;
+    return {
+        enabled: _enabled,
+        driver: _enabled ? (_lastConfig?.driver || 'memory') : 'disabled',
+        size: typeof _driver.size === 'function' ? _driver.size() : null,
+        maxItems: _lastConfig?.memory?.maxItems ?? null,
+        hits: _stats.hits,
+        misses: _stats.misses,
+        writes: _stats.writes,
+        invalidations: _stats.invalidations,
+        hitRate: total > 0 ? _stats.hits / total : null,
+        lastClearedAt: _stats.lastClearedAt,
+        lastInvalidationAt: _stats.lastInvalidationAt,
+        initialisedAt: _stats.initialisedAt
+    };
+}
+
+/**
+ * Get-or-set with in-flight coalescing.
+ *
+ * Producer may return either a raw value, or an object with a `_cacheTags`
+ * array — those tags are merged into opts.tags before storing, and the
+ * `_cacheTags` field is stripped from both the cached and returned value.
+ * This lets producers report tags discovered during rendering (e.g. the
+ * markdown pipeline noting embedded collection slugs) without the caller
+ * needing to know them up front.
+ *
+ * @param {string} key
+ * @param {() => Promise<*>} producer
+ * @param {{ttlSeconds?: number, tags?: string[]}} [opts]
+ */
+export async function wrap(key, producer, opts = {}) {
+    if (!_enabled) {
+        const raw = await producer();
+        return _stripCacheTags(raw);
+    }
+
+    const vkey = _vk(key);
+    const hit = await _driver.get(vkey);
+    if (hit !== undefined) {
+        _stats.hits++;
+        return hit;
+    }
+
+    if (_inflight.has(vkey)) return _inflight.get(vkey);
+
+    _stats.misses++;
+    const promise = (async () => {
+        try {
+            const raw = await producer();
+            const {value, extraTags} = _extractCacheTags(raw);
+            const setOpts = {...opts};
+            if (extraTags) {
+                setOpts.tags = [...(opts.tags ?? []), ...extraTags];
+            }
+            await _driver.set(vkey, value, setOpts);
+            _stats.writes++;
+            return value;
+        } finally {
+            _inflight.delete(vkey);
+        }
+    })();
+
+    _inflight.set(vkey, promise);
+    return promise;
+}
+
+function _vk(key) {
+    return KEY_VERSION + key;
+}
+
+function _extractCacheTags(raw) {
+    if (raw && typeof raw === 'object' && Array.isArray(raw._cacheTags)) {
+        const {_cacheTags, ...value} = raw;
+        return {value, extraTags: _cacheTags};
+    }
+    return {value: raw, extraTags: null};
+}
+
+function _stripCacheTags(raw) {
+    if (raw && typeof raw === 'object' && Array.isArray(raw._cacheTags)) {
+        const {_cacheTags, ...value} = raw;
+        return value;
+    }
+    return raw;
+}
+
+export function _resetForTests() {
+    _driver = new NoneDriver();
+    _enabled = false;
+    _lastConfig = null;
+    _inflight.clear();
+    _stats.hits = 0;
+    _stats.misses = 0;
+    _stats.writes = 0;
+    _stats.invalidations = 0;
+    _stats.lastClearedAt = null;
+    _stats.lastInvalidationAt = null;
+    _stats.initialisedAt = null;
+}

package/server/services/cache/lru.js

@@ -0,0 +1,61 @@
+/**
+ * Bounded LRU built on the insertion-order property of Map.
+ * On hit, delete + re-set the entry so it becomes the most-recent.
+ * On set when at capacity, delete the first (oldest) key.
+ */
+export class LRU {
+    /**
+     * @param {number} maxItems
+     */
+    constructor(maxItems) {
+        if (!Number.isInteger(maxItems) || maxItems < 1) {
+            throw new TypeError('LRU: maxItems must be a positive integer');
+        }
+        this._max = maxItems;
+        this._map = new Map();
+    }
+
+    get size() {
+        return this._map.size;
+    }
+
+    get(key) {
+        if (!this._map.has(key)) return undefined;
+        const value = this._map.get(key);
+        this._map.delete(key);
+        this._map.set(key, value);
+        return value;
+    }
+
+    /** Read without promoting. Use for snapshots / iteration. */
+    peek(key) {
+        return this._map.get(key);
+    }
+
+    /** Iterate `[key, value]` pairs in oldest-to-newest order, no mutation. */
+    entries() {
+        return this._map.entries();
+    }
+
+    set(key, value) {
+        if (this._map.has(key)) {
+            this._map.delete(key);
+        } else if (this._map.size >= this._max) {
+            const oldest = this._map.keys().next().value;
+            this._map.delete(oldest);
+        }
+        this._map.set(key, value);
+    }
+
+    delete(key) {
+        return this._map.delete(key);
+    }
+
+    clear() {
+        this._map.clear();
+    }
+
+    keys() {
+        return this._map.keys();
+    }
+}

package/server/services/collections.js

@@ -11,6 +11,7 @@ import path from 'path';
 import {v4 as uuidv4} from 'uuid';
 import {config} from '../config.js';
 import {getAdapter, invalidate} from './adapterRegistry.js';
+import * as cache from './cache/index.js';
 
 const COLLECTIONS_DIR = path.resolve(config.content.collectionsDir);
 
@@ -149,6 +150,7 @@ export async function createCollection({title, slug, description = '', fields =
 
     await writeSchema(schema);
     await (await getAdapter(finalSlug)).insertMany(finalSlug, []);
+    await cache.invalidateTags([`collection:${finalSlug}`]);
     return schema;
 }
 
@@ -191,6 +193,7 @@ export async function updateCollection(slug, updates) {
 
     // Invalidate cached adapter in case storage config changed.
     invalidate(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
 
     return updated;
 }
@@ -218,6 +221,7 @@ export async function deleteCollection(slug) {
 
     invalidate(slug);
     await fs.rm(collectionDir(slug), { recursive: true, force: true });
+    await cache.invalidateTags([`collection:${slug}`]);
 }
 
 // ---------------------------------------------------------------------------
@@ -304,7 +308,9 @@ export async function createEntry(slug, data, { createdBy = null, source = 'admi
     };
 
     const adapter = await getAdapter(slug);
-    return adapter.insert(slug, entry);
+    const created = await adapter.insert(slug, entry);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return created;
 }
 
 /**
@@ -333,7 +339,9 @@ export async function updateEntry(slug, entryId, data) {
         meta: { ...existing.meta, updatedAt: new Date().toISOString() }
     };
 
-    return adapter.update(slug, entryId, updated);
+    const result = await adapter.update(slug, entryId, updated);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -346,7 +354,9 @@ export async function updateEntry(slug, entryId, data) {
  */
 export async function deleteEntry(slug, entryId) {
     const adapter = await getAdapter(slug);
-    return adapter.remove(slug, entryId);
+    const result = await adapter.remove(slug, entryId);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -359,7 +369,9 @@ export async function clearEntries(slug) {
     const schema = await getCollection(slug);
     if (!schema) throw new Error(`Collection "${slug}" not found`);
     const adapter = await getAdapter(slug);
-    return adapter.clear(slug);
+    const result = await adapter.clear(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -433,6 +445,7 @@ export async function importEntries(slug, incoming, { createdBy = null } = {}) {
     const adapter = await getAdapter(slug);
     if (valid.length > 0) {
         await adapter.insertMany(slug, valid);
+        await cache.invalidateTags([`collection:${slug}`]);
     }
 
     return { imported: valid.length, skipped, errors };

package/server/services/content.js

@@ -9,6 +9,7 @@ import {parseMarkdown, serialiseMarkdown} from './markdown.js';
 import {config} from '../config.js';
 import {hooks} from './hooks.js';
 import {createVersion, deleteAllVersions, renameVersionDir} from './versions.js';
+import * as cache from './cache/index.js';
 
 const CONTENT_DIR = config.content.contentDir;
 const PAGES_DIR = path.join(CONTENT_DIR, 'pages');
@@ -77,6 +78,7 @@ export async function createPage(urlPath, frontmatter, body) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageCreated', {page, urlPath});
     return page;
 }
@@ -111,6 +113,7 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageUpdated', {page, urlPath});
     return page;
 }
@@ -128,6 +131,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
     const newFile = urlPathToFilePath(newUrlPath);
     await fs.mkdir(path.dirname(newFile), { recursive: true });
     await fs.rename(oldFile, newFile);
+    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`]);
     try {
         await renameVersionDir(oldUrlPath, newUrlPath);
     } catch {
@@ -144,6 +148,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageDeleted', {urlPath});
     try {
         await deleteAllVersions(urlPath);
@@ -288,9 +293,9 @@ async function collectMdFiles(dir) {
  */
 async function readPageFile(filePath) {
     const raw = await fs.readFile(filePath, 'utf8');
-    const { data, content, html, usedComponents } = await parseMarkdown(raw);
+    const { data, content, html, usedComponents, tags } = await parseMarkdown(raw);
     const urlPath = filePathToUrlPath(filePath);
-    return { ...data, urlPath, content, html, usedComponents };
+    return { ...data, urlPath, content, html, usedComponents, tags };
 }
 
 /**

package/server/services/forms.js

@@ -6,6 +6,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
+import * as cache from './cache/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT      = path.resolve(__dirname, '..', '..');
@@ -43,6 +44,7 @@ export async function writeForm(slug, data) {
     await ensureFormsDir();
     const file = path.join(FORMS_DIR, `${slug}.json`);
     await fs.writeFile(file, JSON.stringify(data, null, 4) + '\n', 'utf8');
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**
@@ -78,6 +80,7 @@ export async function listForms() {
  */
 export async function deleteForm(slug) {
     await fs.unlink(path.join(FORMS_DIR, `${slug}.json`));
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**

package/server/services/markdown.js

@@ -247,7 +247,7 @@ async function getBlockShortTagNames() {
  * @param {string} content
  * @returns {Promise<string>}
  */
-async function processStaticBlocks(content) {
+async function processStaticBlocks(content, tagSet) {
     // --- [block template="name" .../] ---
     const pattern = /\[block\s+([\s\S]+?)\/\]/g;
     const matches = [...content.matchAll(pattern)];
@@ -262,6 +262,7 @@ async function processStaticBlocks(content) {
             output = output.slice(0, match.index) + output.slice(match.index + match[0].length);
             continue;
         }
+        tagSet?.add(`block:${attrs.template}`);
         let replacement = '';
         try {
             const [tpl, css] = await Promise.all([
@@ -287,6 +288,7 @@ async function processStaticBlocks(content) {
             for (const [, key, dq, sq] of (match[1] ?? '').matchAll(/([\w-]+)=(?:"([^"]*)"|'([^']*)')/g)) {
                 attrs[key] = dq ?? sq ?? '';
             }
+            tagSet?.add(`block:${tagName}`);
             let replacement = '';
             try {
                 const [tpl, css] = await Promise.all([
@@ -458,7 +460,7 @@ function renderCollectionTimeline(entries, opts) {
  * @param {string} markdown
  * @returns {Promise<string>}
  */
-async function processViewBlocks(markdown) {
+async function processViewBlocks(markdown, tagSet) {
     const {scrubbed, restore} = scrubCodeRegions(markdown);
     const pattern = /\[view([^\]]*?)\/\]/gi;
     const matches = [...scrubbed.matchAll(pattern)];
@@ -474,6 +476,7 @@ async function processViewBlocks(markdown) {
             result = result.replace(fullMatch, '');
             continue;
         }
+        tagSet?.add(`view:${slug}`);
 
         const displayAttr = attrs.display || '';
         const emptyMsg   = attrs.empty      || 'No results found';
@@ -579,7 +582,7 @@ async function processViewBlocks(markdown) {
  * @param {string} markdown
  * @returns {Promise<string>}
  */
-async function processCollectionBlocks(markdown) {
+async function processCollectionBlocks(markdown, tagSet) {
     const {scrubbed, restore} = scrubCodeRegions(markdown);
     // Find all [collection ...] shortcodes
     const pattern = /\[collection([^\]]*?)\/\]/gi;
@@ -596,6 +599,7 @@ async function processCollectionBlocks(markdown) {
             result = result.replace(fullMatch, '');
             continue;
         }
+        tagSet?.add(`collection:${slug}`);
 
         const display    = attrs.display || 'table';
         const limitAttr  = parseInt(attrs.limit, 10) || 0;
@@ -1947,11 +1951,13 @@ function processAccordionBlocks(markdown) {
  *   [/carousel]
  *
  * Supported attributes on [carousel]:
- *   autoplay  - "true" to auto-advance slides
- *   interval  - milliseconds between slides (default 5000)
- *   loop      - "false" to disable loop (default true)
- *   animation - "fade" or "slide" (default slide)
- *   id        - optional id on the wrapper
+ *   autoplay           - "true" to auto-advance slides
+ *   interval           - milliseconds between slides (default 5000)
+ *   loop               - "false" to disable loop (default true)
+ *   animation          - "slide" | "fade" | "crossfade" (default slide)
+ *   animation-duration - transition length in milliseconds (default 500)
+ *   animation-easing   - CSS timing function (e.g. ease, linear, ease-in-out, cubic-bezier(...))
+ *   id                 - optional id on the wrapper
  *
  * Supported attributes on [slide]:
  *   image - URL of a background/header image
@@ -1970,7 +1976,9 @@ function processCarouselBlocks(markdown) {
         attrs.autoplay ? ` data-autoplay="${escapeAttr(attrs.autoplay)}"` : '',
         attrs.interval ? ` data-interval="${escapeAttr(attrs.interval)}"` : '',
         attrs.loop ? ` data-loop="${escapeAttr(attrs.loop)}"` : '',
-        attrs.animation ? ` data-animation="${escapeAttr(attrs.animation)}"` : ''
+        attrs.animation ? ` data-animation="${escapeAttr(attrs.animation)}"` : '',
+        attrs['animation-duration'] ? ` data-animation-duration="${escapeAttr(attrs['animation-duration'])}"` : '',
+        attrs['animation-easing'] ? ` data-animation-easing="${escapeAttr(attrs['animation-easing'])}"` : ''
       ].join('');
       const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
 
@@ -2617,7 +2625,7 @@ function processIconBlocks(markdown) {
  */
 const FORMS_DIR = path.resolve(__dirname_md, '../../content/forms');
 
-async function processFormBlocks(markdown) {
+async function processFormBlocks(markdown, tagSet) {
   const {scrubbed, restore} = scrubCodeRegions(markdown);
   const regex = /\[form([^\]]*?)\/\]/gi;
   let result = scrubbed;
@@ -2638,6 +2646,7 @@ async function processFormBlocks(markdown) {
           result = result.slice(0, index) + `<div class="cms-form-error">Invalid form slug: ${escapeAttr(slug)}</div>` + result.slice(index + full.length);
           continue;
       }
+      tagSet?.add(`form:${slug}`);
     let replacement;
     try {
       const filePath = path.resolve(FORMS_DIR, `${slug}.json`);
@@ -2916,9 +2925,10 @@ export async function parseMarkdown(raw) {
   //   → grid → card → slideover → marked → sanitize → afterParse
   const preprocessed = applyTransforms('markdown:beforeParse', content);
   const {output: withComponents, used: usedComponents} = collectAndRewriteComponents(preprocessed);
-  const withCollection = await processCollectionBlocks(withComponents);
-  const withView = await processViewBlocks(withCollection);
-  const withStaticBlock = await processStaticBlocks(withView);
+  const tagSet = new Set();
+  const withCollection = await processCollectionBlocks(withComponents, tagSet);
+  const withView = await processViewBlocks(withCollection, tagSet);
+  const withStaticBlock = await processStaticBlocks(withView, tagSet);
   const withDconfig = processDConfigBlocks(withStaticBlock);
     const withEffects = processEffectsBlocks(withDconfig);
     const withPluginShortcodes = await processPluginShortcodes(withEffects);
@@ -2931,7 +2941,7 @@ export async function parseMarkdown(raw) {
     const withSpacer = processSpacerBlocks(withListGroup);
     const withCenter = processCenterBlocks(withSpacer);
     const withIcon = processIconBlocks(withCenter);
-  const withForm = await processFormBlocks(withIcon);
+  const withForm = await processFormBlocks(withIcon, tagSet);
   const withHero = processHeroBlocks(withForm);
   const withTable = processTableBlocks(withHero);
   const withBadge  = processBadgeBlocks(withTable);
@@ -2997,7 +3007,7 @@ export async function parseMarkdown(raw) {
   const allowed = new Set(_dmTagAllowlist.map(t => t.replace(/^dm-/, '')));
   const filteredUsed = [...usedComponents].filter(name => allowed.has(name));
 
-  return {data, content, html, usedComponents: filteredUsed};
+  return {data, content, html, usedComponents: filteredUsed, tags: [...tagSet]};
 }
 
 /**

package/server/services/views.js

@@ -14,6 +14,7 @@
  */
 import {v4 as uuidv4} from 'uuid';
 import {buildRowLevelMatch} from './rowAccess.js';
+import * as cache from './cache/index.js';
 
 /** MongoDB collection where view configs are stored. */
 const VIEWS_COLLECTION = 'cms__views';
@@ -173,6 +174,7 @@ export async function createView(data, userId = null) {
     };
 
     await db.collection(VIEWS_COLLECTION).insertOne({ ...view });
+    await cache.invalidateTags([`view:${slug}`]);
     return view;
 }
 
@@ -206,6 +208,7 @@ export async function updateView(slug, data) {
     };
 
     await db.collection(VIEWS_COLLECTION).replaceOne({ slug }, { ...updated });
+    await cache.invalidateTags([`view:${slug}`]);
     const { _id: _stripped, ...result } = updated;
     return result;
 }
@@ -221,6 +224,7 @@ export async function deleteView(slug) {
     const db = await getMetaDb();
     const result = await db.collection(VIEWS_COLLECTION).deleteOne({ slug });
     if (result.deletedCount === 0) throw new Error(`View "${slug}" not found`);
+    await cache.invalidateTags([`view:${slug}`]);
 }
 
 // ---------------------------------------------------------------------------