http-cache-semantics 4.2.0: satisfiesWithoutRevalidation

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify http-cache-semantics.satisfiesWithoutRevalidation in pkg:npm/http-cache-semantics@4.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/http-cache-semantics@4.2.0
Demonstrate these symbols/APIs:
  - http-cache-semantics.satisfiesWithoutRevalidation

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:568de5f5424d1da6f881483326f59a07c8b56315b32082c42f76191690f80de4","contract":["satisfiesWithoutRevalidation returns true when fresh cached response matches incoming GET request","satisfiesWithoutRevalidation returns false when cached response is stale without max-stale","satisfiesWithoutRevalidation returns true when stale cached response is allowed by request max-stale","satisfiesWithoutRevalidation returns false when incoming request method, URL, or host does not match","satisfiesWithoutRevalidation returns false when request contains no-cache directive in Cache-Control or Pragma","satisfiesWithoutRevalidation returns false when response contains must-revalidate directive","satisfiesWithoutRevalidation returns false when request min-fresh exceeds remaining freshness lifetime","satisfiesWithoutRevalidation returns false when request headers do not match response Vary specification","satisfiesWithoutRevalidation throws Error when incoming request or its headers are missing"],"goal":"verify http-cache-semantics.satisfiesWithoutRevalidation in pkg:npm/http-cache-semantics@4.2.0","kind":"HOW","packages":["pkg:npm/http-cache-semantics@4.2.0"],"schemaVersion":1,"symbols":["http-cache-semantics.satisfiesWithoutRevalidation"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/http-cache-semantics@4.2.0"],"schemaVersion":1,"subject":"pkg:npm/http-cache-semantics@4.2.0","symbols":["http-cache-semantics.satisfiesWithoutRevalidation"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-http-cache-semantics",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-http-cache-semantics",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "http-cache-semantics": "4.2.0"
      }
    },
    "node_modules/http-cache-semantics": {
      "version": "4.2.0",
      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
      "license": "BSD-2-Clause"
    }
  }
}

{
  "name": "sample-http-cache-semantics",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for http-cache-semantics@4.2.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "http-cache-semantics": "4.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify http-cache-semantics.satisfiesWithoutRevalidation in pkg:npm/http-cache-semantics@4.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/http-cache-semantics@4.2.0"
  ],
  "symbols": [
    "http-cache-semantics.satisfiesWithoutRevalidation"
  ]
}

'use strict';

const CachePolicy = require('http-cache-semantics');

/**
 * Creates a new CachePolicy instance.
 *
 * @param {object} req - HTTP request representation.
 * @param {object} res - HTTP response representation.
 * @param {object} [options] - Cache policy options.
 * @returns {CachePolicy} The created cache policy.
 */
function createPolicy(req, res, options) {
  return new CachePolicy(req, res, options);
}

/**
 * Evaluates whether a cached response satisfies an incoming request without revalidation.
 *
 * @param {CachePolicy} policy - Current CachePolicy instance.
 * @param {object} req - Incoming HTTP request representation.
 * @returns {boolean} True if the cached response satisfies the request without revalidation.
 */
function satisfiesWithoutRevalidation(policy, req) {
  return policy.satisfiesWithoutRevalidation(req);
}

module.exports = {
  CachePolicy,
  createPolicy,
  satisfiesWithoutRevalidation,
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { CachePolicy, createPolicy, satisfiesWithoutRevalidation } = require('../src/index.js');

async function testAll() {
  // Export and symbol verification
  assert.equal(typeof CachePolicy, 'function', 'CachePolicy should be a constructor function');
  assert.equal(typeof createPolicy, 'function', 'createPolicy should be a function');
  assert.equal(typeof satisfiesWithoutRevalidation, 'function', 'satisfiesWithoutRevalidation should be a function');
  assert.equal(
    typeof CachePolicy.prototype.satisfiesWithoutRevalidation,
    'function',
    'CachePolicy.prototype.satisfiesWithoutRevalidation must be a function'
  );

  const baseReq = {
    url: '/api/resource',
    method: 'GET',
    headers: { host: 'example.com' },
  };

  // 1. satisfiesWithoutRevalidation returns true when fresh cached response matches incoming GET request
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);
    assert.equal(policy.satisfiesWithoutRevalidation(baseReq), true);
    assert.equal(satisfiesWithoutRevalidation(policy, baseReq), true);
  }

  // 2. satisfiesWithoutRevalidation returns false when cached response is stale without max-stale
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=0',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);
    assert.equal(policy.stale(), true);
    assert.equal(policy.satisfiesWithoutRevalidation(baseReq), false);
    assert.equal(satisfiesWithoutRevalidation(policy, baseReq), false);
  }

  // 3. satisfiesWithoutRevalidation returns true when stale cached response is allowed by request max-stale
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=0',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);
    const reqWithMaxStale = {
      url: '/api/resource',
      method: 'GET',
      headers: {
        host: 'example.com',
        'cache-control': 'max-stale=100',
      },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqWithMaxStale), true);
    assert.equal(satisfiesWithoutRevalidation(policy, reqWithMaxStale), true);
  }

  // 4. satisfiesWithoutRevalidation returns false when incoming request method, URL, or host does not match
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);

    const reqPost = { url: '/api/resource', method: 'POST', headers: { host: 'example.com' } };
    assert.equal(policy.satisfiesWithoutRevalidation(reqPost), false);

    const reqOtherUrl = { url: '/api/other', method: 'GET', headers: { host: 'example.com' } };
    assert.equal(policy.satisfiesWithoutRevalidation(reqOtherUrl), false);

    const reqOtherHost = { url: '/api/resource', method: 'GET', headers: { host: 'other.example.com' } };
    assert.equal(policy.satisfiesWithoutRevalidation(reqOtherHost), false);
  }

  // 5. satisfiesWithoutRevalidation returns false when request contains no-cache directive in Cache-Control or Pragma
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);

    const reqNoCache = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'cache-control': 'no-cache' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqNoCache), false);

    const reqPragmaNoCache = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', pragma: 'no-cache' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqPragmaNoCache), false);
  }

  // 6. satisfiesWithoutRevalidation returns false when response contains must-revalidate directive
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600, must-revalidate',
        etag: '"tag-v1"',
      },
    };
    const policy = createPolicy(baseReq, res);
    assert.equal(policy.satisfiesWithoutRevalidation(baseReq), false);
  }

  // 7. satisfiesWithoutRevalidation returns false when request min-fresh exceeds remaining freshness lifetime
  {
    const res = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600',
      },
    };
    const policy = createPolicy(baseReq, res);
    const reqMinFreshExceeded = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'cache-control': 'min-fresh=7200' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqMinFreshExceeded), false);

    const reqMinFreshSatisfied = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'cache-control': 'min-fresh=60' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqMinFreshSatisfied), true);
  }

  // 8. satisfiesWithoutRevalidation returns false when request headers do not match response Vary specification
  {
    const reqVary = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'accept-encoding': 'gzip' },
    };
    const resVary = {
      status: 200,
      headers: {
        'cache-control': 'public, max-age=3600',
        vary: 'accept-encoding',
      },
    };
    const policy = createPolicy(reqVary, resVary);

    const reqMatchingVary = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'accept-encoding': 'gzip' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqMatchingVary), true);

    const reqDifferingVary = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'accept-encoding': 'br' },
    };
    assert.equal(policy.satisfiesWithoutRevalidation(reqDifferingVary), false);
  }

  // 9. satisfiesWithoutRevalidation throws Error when incoming request or its headers are missing
  {
    const res = {
      status: 200,
      headers: { 'cache-control': 'public, max-age=3600' },
    };
    const policy = createPolicy(baseReq, res);

    assert.throws(
      () => policy.satisfiesWithoutRevalidation(null),
      /Request headers missing/
    );
    assert.throws(
      () => policy.satisfiesWithoutRevalidation({}),
      /Request headers missing/
    );
  }

  console.log('All http-cache-semantics satisfiesWithoutRevalidation contract assertions passed.');
}

testAll().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});