express-cache-ctrl 1.1.6 → 1.1.9

package/.github/renovate.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+    "extends": [
+        "config:base"
+    ],
+    "semanticCommits": "enabled",
+    "rangeStrategy": "bump",
+    "packageRules": [
+        {
+            "matchUpdateTypes": [
+                "major"
+            ],
+            "enabled": false
+        }
+    ]
+}

package/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md
+
+This file provides guidelines for AI coding agents working on the express-cache-ctrl repository.
+
+## Project Overview
+
+An Express.js middleware for managing Cache-Control headers with support for public/private caching, TTL, and OWASP secure caching recommendations.
+
+## Build/Test Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npx mocha 'test/cache.js'
+npx mocha 'test/unit/cache.js'
+
+# Run tests matching a pattern (grep)
+npx mocha 'test/**/*.js' --grep "cache disabled"
+
+# Run with different reporter
+npx mocha 'test/**/*.js' --reporter spec
+```
+
+Note: This project uses Mocha (test runner) + Chai (assertions). Tests use BDD style with `describe()` and `it()` blocks.
+
+## Code Style Guidelines
+
+### Formatting
+- Indent: 4 spaces for `.js` files, 2 spaces for `package.json` (see `.editorconfig`)
+- Use double quotes for strings
+- Always use semicolons
+- Insert final newline at end of files
+- Trim trailing whitespace
+
+### Language & Imports
+- Use ES5/CommonJS (no ES6 modules)
+- Import style: `const module = require("module");`
+- Use `"use strict";` directive at top of source files
+- Node.js version: >= 12.0
+
+### Naming Conventions
+- Functions: camelCase (e.g., `cacheCustom`, `toTimespan`)
+- Variables: camelCase (e.g., `cacheControl`, `defaultTTL`)
+- Constants: Use descriptive names, may use ALL_CAPS for true constants
+- Files: camelCase for source files (e.g., `cache.js`)
+
+### Functions & Structure
+- Prefer traditional function declarations over arrow functions in source
+- Arrow functions acceptable in tests
+- Group related functions together with clear section comments
+- Export pattern: `exports.functionName = functionName;` at end of file
+
+### Testing Conventions
+- Test files: Located in `test/` directory with `.js` extension
+- Unit tests: Place in `test/unit/` subdirectory
+- Mock objects: Place in `test/mocks/` subdirectory
+- Use Chai's `expect()` assertion style
+- Use descriptive test names that explain behavior
+- Group related tests with nested `describe()` blocks
+- Follow pattern: `it("should do something", function (done) { ... });`
+- Call `done()` callback for async tests
+
+### Error Handling
+- Middleware must call `next()` to pass control
+- Validate inputs with truthy checks: `opts = opts || {};`
+- Use `parseInt()` for numeric conversions
+- Avoid throwing errors for expected edge cases
+
+### Comments
+- Use `//` for single-line comments
+- Add descriptive headers for sections: `// Public functions`, `// Module requires`
+- JSDoc-style comments acceptable but not required
+
+## File Organization
+
+```
+src/
+  cache.js          # Main middleware implementation
+test/
+  cache.js          # Integration tests
+  unit/
+    cache.js        # Unit tests for internal functions
+  mocks/
+    response.js     # Mock Express response object
+```
+
+## Dependencies
+
+Production:
+- express: ^4.18.2
+- ms: ^2.1.3
+
+Development:
+- mocha: ^10.2.0
+- chai: ^4.3.7
+- mock-res: ^0.6.0
+
+## Important Notes
+
+- Default TTL is "1h" (3600 seconds) when not specified
+- Uses `ms` library for human-readable time parsing
+- Middleware follows Express convention: `(req, res, next) => {}`
+- Supports both `res.setHeader()` and `res.set()` methods
+- Always exports internal functions for testability

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "express-cache-ctrl",
-  "version": "1.1.6",
+  "version": "1.1.9",
   "description": "Express middleware to handle content expiration using Cache-Control header.",
   "main": "src/cache.js",
   "scripts": {
-    "test": "mocha test/"
+    "test": "mocha 'test/**/*.js'"
   },
   "repository": {
     "type": "git",
@@ -22,13 +22,13 @@
   "author": "Carlos Luis Castro Márquez <carlosluiscastro@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "express": "^4.18.2",
+    "express": "^4.22.1",
     "ms": "^2.1.3"
   },
   "devDependencies": {
-    "chai": "^4.3.7",
-    "mocha": "^10.2.0",
+    "chai": "^4.5.0",
+    "mocha": "^10.8.2",
     "mock-res": "^0.6.0",
-    "morgan": "^1.10.0"
+    "morgan": "^1.10.1"
   }
 }

package/src/cache.js

@@ -120,3 +120,4 @@ exports.secure = cacheSecure;
 exports.public = cachePublic;
 exports.private = cachePrivate;
 exports.toTimespan = toTimespan;
+exports.generateHeader = generateHeader;

package/test/cache.js

@@ -154,6 +154,123 @@ describe("Cache Middleware", function () {
         });
     });
 
+    describe("Edge Cases", function () {
+        it("cache private with TTL = 0 defaults to defaultTTL", function (done) {
+            const middleware = cache.private(0);
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                const defaultTtlSeconds = cache.toTimespan(cache.defaultTTL);
+                // 0 is falsy, so it defaults to defaultTTL (1h = 3600)
+                expect(controls).to.property("max-age").and.to.equal(defaultTtlSeconds);
+                done();
+            });
+        });
+
+        it("cache public with string TTL '1d'", function (done) {
+            const middleware = cache.public("1d");
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("max-age").and.to.equal(86400);
+                expect(controls).to.property("s-maxage").and.to.equal(86400);
+                done();
+            });
+        });
+
+        it("cache public with string TTL '2h'", function (done) {
+            const middleware = cache.public("2h");
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("max-age").and.to.equal(7200);
+                expect(controls).to.property("s-maxage").and.to.equal(7200);
+                done();
+            });
+        });
+
+        it("cache public with string TTL '30m'", function (done) {
+            const middleware = cache.public("30m");
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("max-age").and.to.equal(1800);
+                expect(controls).to.property("s-maxage").and.to.equal(1800);
+                done();
+            });
+        });
+
+        it("cache custom with no options", function (done) {
+            const middleware = cache.custom();
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                expect(cacheControl).to.not.be.null;
+                expect(cacheControl).to.be.a("string");
+                done();
+            });
+        });
+
+        it("cache custom with empty options", function (done) {
+            const middleware = cache.custom({});
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                expect(cacheControl).to.not.be.null;
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("private");
+                done();
+            });
+        });
+
+        it("should remove Pragma header when noCache is false", function (done) {
+            const middleware = cache.private(3600);
+            const res = new Response();
+            // Set Pragma header first
+            res.setHeader("Pragma", "no-cache");
+            middleware.call(middleware, {}, res, function () {
+                const pragma = res.get("Pragma");
+                expect(pragma).to.be.undefined;
+                done();
+            });
+        });
+
+        it("should call next() callback", function (done) {
+            const middleware = cache.private(3600);
+            const res = new Response();
+            let nextCalled = false;
+            middleware.call(middleware, {}, res, function () {
+                nextCalled = true;
+                expect(nextCalled).to.be.true;
+                done();
+            });
+        });
+
+        it("cache public with 1 week TTL", function (done) {
+            const middleware = cache.public("1w");
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("max-age").and.to.equal(604800);
+                expect(controls).to.property("s-maxage").and.to.equal(604800);
+                done();
+            });
+        });
+
+        it("cache custom with different max-age and s-maxage", function (done) {
+            const middleware = cache.custom({
+                scope: "public",
+                ttl: "2h",
+                sttl: "1h",
+            });
+            runMiddleware(middleware, function (res) {
+                const cacheControl = res.get("Cache-Control");
+                const controls = parseCacheControl(cacheControl);
+                expect(controls).to.property("max-age").and.to.equal(7200);
+                expect(controls).to.property("s-maxage").and.to.equal(3600);
+                done();
+            });
+        });
+    });
+
     function runMiddleware(middleware, callback) {
         const res = new Response();
         middleware.call(middleware, {}, res, function () {

package/test/unit/cache.js

@@ -0,0 +1,253 @@
+const { expect } = require("chai");
+const cache = require("../../src/cache");
+
+describe("Cache Internal Functions", function () {
+    describe("toTimespan()", function () {
+        describe("numeric inputs", function () {
+            it("should return numeric value as-is for positive integers", function () {
+                expect(cache.toTimespan(3600)).to.equal(3600);
+                expect(cache.toTimespan(60)).to.equal(60);
+                expect(cache.toTimespan(1)).to.equal(1);
+            });
+
+            it("should return numeric value for large numbers", function () {
+                expect(cache.toTimespan(86400)).to.equal(86400);
+                expect(cache.toTimespan(31536000)).to.equal(31536000);
+            });
+
+            it("should return 0 for zero value", function () {
+                expect(cache.toTimespan(0)).to.equal(0);
+            });
+        });
+
+        describe("string inputs", function () {
+            it("should convert days to seconds", function () {
+                expect(cache.toTimespan("1d")).to.equal(86400);
+                expect(cache.toTimespan("2d")).to.equal(172800);
+                expect(cache.toTimespan("7d")).to.equal(604800);
+            });
+
+            it("should convert hours to seconds", function () {
+                expect(cache.toTimespan("1h")).to.equal(3600);
+                expect(cache.toTimespan("2h")).to.equal(7200);
+                expect(cache.toTimespan("24h")).to.equal(86400);
+            });
+
+            it("should convert minutes to seconds", function () {
+                expect(cache.toTimespan("1m")).to.equal(60);
+                expect(cache.toTimespan("30m")).to.equal(1800);
+                expect(cache.toTimespan("60m")).to.equal(3600);
+            });
+
+            it("should convert seconds to seconds", function () {
+                expect(cache.toTimespan("1s")).to.equal(1);
+                expect(cache.toTimespan("30s")).to.equal(30);
+                expect(cache.toTimespan("60s")).to.equal(60);
+            });
+
+            it("should convert weeks to seconds", function () {
+                expect(cache.toTimespan("1w")).to.equal(604800);
+                expect(cache.toTimespan("2w")).to.equal(1209600);
+            });
+
+            it("should convert milliseconds to seconds", function () {
+                expect(cache.toTimespan("1000ms")).to.equal(1);
+                expect(cache.toTimespan("60000ms")).to.equal(60);
+            });
+
+            it("should return NaN for compound time strings (not supported)", function () {
+                // The ms library doesn't support compound time strings
+                expect(cache.toTimespan("1h30m")).to.be.NaN;
+                expect(cache.toTimespan("1d12h")).to.be.NaN;
+            });
+        });
+
+        describe("edge cases", function () {
+            it("should handle negative numbers", function () {
+                expect(cache.toTimespan(-3600)).to.equal(-3600);
+            });
+
+            it("should return NaN for invalid string input", function () {
+                expect(cache.toTimespan("invalid")).to.be.NaN;
+            });
+
+            it("should handle floating point numbers", function () {
+                expect(cache.toTimespan(3600.5)).to.equal(3600);
+            });
+        });
+    });
+
+    describe("generateHeader()", function () {
+        describe("scope handling", function () {
+            it("should add public scope when specified", function () {
+                const result = cache.generateHeader({ scope: "public" });
+                expect(result).to.include("public");
+            });
+
+            it("should add private scope when specified", function () {
+                const result = cache.generateHeader({ scope: "private" });
+                expect(result).to.include("private");
+            });
+
+            it("should default to private when no scope is specified and not no-cache", function () {
+                const result = cache.generateHeader({ ttl: 3600 });
+                expect(result).to.include("private");
+            });
+        });
+
+        describe("noCache handling", function () {
+            it("should add no-cache and no-store when noCache is true", function () {
+                const result = cache.generateHeader({ noCache: true });
+                expect(result).to.include("no-cache");
+                expect(result).to.include("no-store");
+            });
+
+            it("should not add max-age when noCache is true", function () {
+                const result = cache.generateHeader({ noCache: true, ttl: 3600 });
+                const hasMaxAge = result.some(item => item.startsWith("max-age="));
+                expect(hasMaxAge).to.be.false;
+            });
+
+            it("should not add private scope when noCache is true without explicit scope", function () {
+                const result = cache.generateHeader({ noCache: true });
+                expect(result).to.not.include("private");
+            });
+
+            it("should respect explicit scope even with noCache", function () {
+                const result = cache.generateHeader({ noCache: true, scope: "public" });
+                expect(result).to.include("public");
+            });
+        });
+
+        describe("TTL handling", function () {
+            it("should add max-age with numeric TTL", function () {
+                const result = cache.generateHeader({ ttl: 3600 });
+                expect(result).to.include("max-age=3600");
+            });
+
+            it("should add max-age with string TTL", function () {
+                const result = cache.generateHeader({ ttl: "1h" });
+                expect(result).to.include("max-age=3600");
+            });
+
+            it("should use default TTL when not specified", function () {
+                const result = cache.generateHeader({});
+                const defaultTtlSeconds = cache.toTimespan(cache.defaultTTL);
+                expect(result).to.include(`max-age=${defaultTtlSeconds}`);
+            });
+
+            it("should add s-maxage when sttl is specified", function () {
+                const result = cache.generateHeader({ ttl: 3600, sttl: 7200 });
+                expect(result).to.include("s-maxage=7200");
+            });
+
+            it("should add s-maxage with string sttl", function () {
+                const result = cache.generateHeader({ ttl: 3600, sttl: "2h" });
+                expect(result).to.include("s-maxage=7200");
+            });
+        });
+
+        describe("revalidation flags", function () {
+            it("should add must-revalidate when specified", function () {
+                const result = cache.generateHeader({ mustRevalidate: true });
+                expect(result).to.include("must-revalidate");
+            });
+
+            it("should add proxy-revalidate when specified", function () {
+                const result = cache.generateHeader({ proxyRevalidate: true });
+                expect(result).to.include("proxy-revalidate");
+            });
+
+            it("should add both revalidation flags when both specified", function () {
+                const result = cache.generateHeader({
+                    mustRevalidate: true,
+                    proxyRevalidate: true,
+                });
+                expect(result).to.include("must-revalidate");
+                expect(result).to.include("proxy-revalidate");
+            });
+
+            it("should not add revalidation flags when not specified", function () {
+                const result = cache.generateHeader({ ttl: 3600 });
+                expect(result).to.not.include("must-revalidate");
+                expect(result).to.not.include("proxy-revalidate");
+            });
+        });
+
+        describe("no-transform flag", function () {
+            it("should add no-transform when specified", function () {
+                const result = cache.generateHeader({ noTransform: true });
+                expect(result).to.include("no-transform");
+            });
+
+            it("should not add no-transform when not specified", function () {
+                const result = cache.generateHeader({ ttl: 3600 });
+                expect(result).to.not.include("no-transform");
+            });
+        });
+
+        describe("complex scenarios", function () {
+            it("should generate correct header for public cache with all options", function () {
+                const result = cache.generateHeader({
+                    scope: "public",
+                    ttl: 3600,
+                    sttl: 7200,
+                    mustRevalidate: true,
+                    proxyRevalidate: true,
+                    noTransform: true,
+                });
+
+                expect(result).to.include("public");
+                expect(result).to.include("max-age=3600");
+                expect(result).to.include("s-maxage=7200");
+                expect(result).to.include("must-revalidate");
+                expect(result).to.include("proxy-revalidate");
+                expect(result).to.include("no-transform");
+            });
+
+            it("should generate correct header for disabled cache", function () {
+                const result = cache.generateHeader({
+                    noCache: true,
+                    mustRevalidate: true,
+                    proxyRevalidate: true,
+                });
+
+                expect(result).to.include("no-cache");
+                expect(result).to.include("no-store");
+                expect(result).to.include("must-revalidate");
+                expect(result).to.include("proxy-revalidate");
+            });
+
+            it("should generate correct header for secure cache", function () {
+                const result = cache.generateHeader({
+                    scope: "private",
+                    noCache: true,
+                    mustRevalidate: true,
+                    noTransform: true,
+                });
+
+                expect(result).to.include("private");
+                expect(result).to.include("no-cache");
+                expect(result).to.include("no-store");
+                expect(result).to.include("must-revalidate");
+                expect(result).to.include("no-transform");
+            });
+
+            it("should handle empty options object", function () {
+                const result = cache.generateHeader({});
+                expect(result).to.be.an("array");
+                expect(result.length).to.be.greaterThan(0);
+            });
+
+            it("should throw error for undefined options", function () {
+                // The code doesn't handle undefined, which is expected behavior
+                expect(() => cache.generateHeader(undefined)).to.throw(TypeError);
+            });
+
+            it("should throw error for null options", function () {
+                // The code doesn't handle null, which is expected behavior
+                expect(() => cache.generateHeader(null)).to.throw(TypeError);
+            });
+        });
+    });
+});