@pantheon-systems/nextjs-cache-handler 0.1.0

package/dist/utils/tags-buffer.js

@@ -0,0 +1,181 @@
+import { createLogger } from './logger.js';
+/**
+ * Buffers tag mapping updates to avoid GCS rate limiting.
+ * Collects updates in memory and flushes them at most once per second.
+ */
+export class TagsBuffer {
+    constructor(config) {
+        this.pendingUpdates = [];
+        this.flushTimer = null;
+        this.lastFlushTime = 0;
+        this.isFlushing = false;
+        this.flushPromise = null;
+        this.flushIntervalMs = config.flushIntervalMs ?? 1000;
+        this.readTagsMapping = config.readTagsMapping;
+        this.writeTagsMapping = config.writeTagsMapping;
+        this.log = createLogger(config.handlerName ?? 'TagsBuffer');
+    }
+    /**
+     * Queue a tag addition for a cache key.
+     * The update will be flushed to storage at most once per second.
+     */
+    addTags(cacheKey, tags) {
+        if (tags.length === 0) {
+            return;
+        }
+        this.pendingUpdates.push({
+            type: 'add',
+            cacheKey,
+            tags,
+        });
+        this.scheduleFlush();
+    }
+    /**
+     * Queue a cache key deletion from all tags.
+     * The update will be flushed to storage at most once per second.
+     */
+    deleteKey(cacheKey) {
+        this.pendingUpdates.push({
+            type: 'delete',
+            cacheKey,
+        });
+        this.scheduleFlush();
+    }
+    /**
+     * Queue multiple cache keys for deletion from all tags.
+     */
+    deleteKeys(cacheKeys) {
+        for (const cacheKey of cacheKeys) {
+            this.pendingUpdates.push({
+                type: 'delete',
+                cacheKey,
+            });
+        }
+        if (cacheKeys.length > 0) {
+            this.scheduleFlush();
+        }
+    }
+    /**
+     * Force an immediate flush of pending updates.
+     * Use this when you need to ensure updates are persisted (e.g., before reading).
+     */
+    async flush() {
+        // If already flushing, wait for that to complete
+        if (this.flushPromise) {
+            await this.flushPromise;
+            // After waiting, check if there are still pending updates
+            if (this.pendingUpdates.length > 0) {
+                return this.flush();
+            }
+            return;
+        }
+        if (this.pendingUpdates.length === 0) {
+            return;
+        }
+        this.flushPromise = this.doFlush();
+        try {
+            await this.flushPromise;
+        }
+        finally {
+            this.flushPromise = null;
+        }
+    }
+    /**
+     * Get the number of pending updates.
+     */
+    get pendingCount() {
+        return this.pendingUpdates.length;
+    }
+    scheduleFlush() {
+        // If a timer is already scheduled, let it handle the flush
+        if (this.flushTimer) {
+            return;
+        }
+        const timeSinceLastFlush = Date.now() - this.lastFlushTime;
+        const delay = Math.max(0, this.flushIntervalMs - timeSinceLastFlush);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush().catch((error) => {
+                this.log.error('Error during scheduled flush:', error);
+            });
+        }, delay);
+    }
+    async doFlush() {
+        if (this.isFlushing || this.pendingUpdates.length === 0) {
+            return;
+        }
+        this.isFlushing = true;
+        // Take all pending updates
+        const updates = this.pendingUpdates;
+        this.pendingUpdates = [];
+        try {
+            // Read current state
+            const tagsMapping = await this.readTagsMapping();
+            // Apply all updates
+            this.applyUpdates(tagsMapping, updates);
+            // Write back
+            await this.writeTagsMapping(tagsMapping);
+            this.lastFlushTime = Date.now();
+            this.log.debug(`Flushed ${updates.length} tag updates`);
+        }
+        catch (error) {
+            // On failure, put updates back for retry
+            this.pendingUpdates = [...updates, ...this.pendingUpdates];
+            this.log.error('Error flushing tags, will retry:', error);
+            // Schedule a retry with backoff
+            if (!this.flushTimer) {
+                this.flushTimer = setTimeout(() => {
+                    this.flushTimer = null;
+                    this.flush().catch((e) => {
+                        this.log.error('Retry flush failed:', e);
+                    });
+                }, this.flushIntervalMs * 2);
+            }
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    applyUpdates(tagsMapping, updates) {
+        // Collect all keys to delete for efficient removal
+        const keysToDelete = new Set();
+        for (const update of updates) {
+            if (update.type === 'delete') {
+                keysToDelete.add(update.cacheKey);
+            }
+        }
+        // Remove deleted keys from all tags
+        if (keysToDelete.size > 0) {
+            for (const tag of Object.keys(tagsMapping)) {
+                tagsMapping[tag] = tagsMapping[tag].filter((key) => !keysToDelete.has(key));
+                if (tagsMapping[tag].length === 0) {
+                    delete tagsMapping[tag];
+                }
+            }
+        }
+        // Add new tag mappings
+        for (const update of updates) {
+            if (update.type === 'add' && update.tags) {
+                for (const tag of update.tags) {
+                    if (!tagsMapping[tag]) {
+                        tagsMapping[tag] = [];
+                    }
+                    if (!tagsMapping[tag].includes(update.cacheKey)) {
+                        tagsMapping[tag].push(update.cacheKey);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Cancel any pending flush timer.
+     * Call this when shutting down.
+     */
+    destroy() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=tags-buffer.js.map

package/dist/utils/tags-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags-buffer.js","sourceRoot":"","sources":["../../src/utils/tags-buffer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pantheon-systems/nextjs-cache-handler",
+  "version": "0.1.0",
+  "description": "Custom cache handler for Next.js with support for Google Cloud Storage and file-based caching",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "next.js",
+    "cache",
+    "cache-handler",
+    "gcs",
+    "google-cloud-storage",
+    "pantheon"
+  ],
+  "author": "Pantheon Systems",
+  "license": "MIT",
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "dependencies": {
+    "@google-cloud/storage": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pantheon-systems/nextjs-cache-handler"
+  },
+  "homepage": "https://github.com/pantheon-systems/nextjs-cache-handler#readme",
+  "bugs": {
+    "url": "https://github.com/pantheon-systems/nextjs-cache-handler/issues"
+  }
+}