http-cache-semantics 4.2.0: storable

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.storable 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.storable

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:240c2f51071efba163c63528e2663613cd24d4bd1ba688057df0ff41f6b00562","contract":["storable returns true for standard cacheable GET response with default 200 status","storable returns false when request contains no-store directive","storable returns false when response contains no-store directive","storable returns true for HEAD request with cacheable response","storable returns false for POST request without explicit expiration","storable returns true for POST request with explicit max-age expiration","storable returns false for uncacheable request methods like PUT or DELETE","storable returns false for private response in a default shared cache","storable returns true for private response in a non-shared private cache","storable returns false for authenticated request in shared cache without public directive","storable returns true for authenticated request in shared cache with public directive","storable returns false for status code 302 without explicit expiration","storable returns true for status code 302 with explicit max-age expiration","storable returns false for status code 502 not understood by cache"],"goal":"verify http-cache-semantics.storable 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.storable"]},"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.storable"],"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 storable",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "http-cache-semantics": "4.2.0"
  }
}

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

'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);
}

/**
 * Determines if the response is storable in a cache.
 *
 * @param {CachePolicy} policy - Current CachePolicy instance.
 * @returns {boolean} True if the response can be stored in cache.
 */
function isStorable(policy) {
  return policy.storable();
}

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

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

const require = createRequire(import.meta.url);
const { CachePolicy, createPolicy, isStorable } = 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 isStorable, 'function', 'isStorable should be a function');
  assert.equal(
    typeof CachePolicy.prototype.storable,
    'function',
    'CachePolicy.prototype.storable must be a function'
  );

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

  // 1. storable returns true for standard cacheable GET response with default 200 status
  {
    const res = {
      status: 200,
      headers: { 'cache-control': 'public, max-age=3600' },
    };
    const policy = createPolicy(baseReq, res);
    assert.equal(policy.storable(), true);
    assert.equal(isStorable(policy), true);
  }

  // 2. storable returns false when request contains no-store directive
  {
    const reqNoStore = {
      url: '/api/resource',
      method: 'GET',
      headers: { host: 'example.com', 'cache-control': 'no-store' },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'public, max-age=3600' },
    };
    const policy = createPolicy(reqNoStore, res);
    assert.equal(policy.storable(), false);
    assert.equal(isStorable(policy), false);
  }

  // 3. storable returns false when response contains no-store directive
  {
    const resNoStore = {
      status: 200,
      headers: { 'cache-control': 'no-store' },
    };
    const policy = createPolicy(baseReq, resNoStore);
    assert.equal(policy.storable(), false);
    assert.equal(isStorable(policy), false);
  }

  // 4. storable returns true for HEAD request with cacheable response
  {
    const reqHead = {
      url: '/api/resource',
      method: 'HEAD',
      headers: { host: 'example.com' },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'max-age=3600' },
    };
    const policy = createPolicy(reqHead, res);
    assert.equal(policy.storable(), true);
    assert.equal(isStorable(policy), true);
  }

  // 5. storable returns false for POST request without explicit expiration
  {
    const reqPost = {
      url: '/api/resource',
      method: 'POST',
      headers: { host: 'example.com' },
    };
    const res = {
      status: 200,
      headers: {},
    };
    const policy = createPolicy(reqPost, res);
    assert.equal(policy.storable(), false);
    assert.equal(isStorable(policy), false);
  }

  // 6. storable returns true for POST request with explicit max-age expiration
  {
    const reqPost = {
      url: '/api/resource',
      method: 'POST',
      headers: { host: 'example.com' },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'max-age=3600' },
    };
    const policy = createPolicy(reqPost, res);
    assert.equal(policy.storable(), true);
    assert.equal(isStorable(policy), true);
  }

  // 7. storable returns false for uncacheable request methods like PUT or DELETE
  {
    const reqPut = {
      url: '/api/resource',
      method: 'PUT',
      headers: { host: 'example.com' },
    };
    const reqDelete = {
      url: '/api/resource',
      method: 'DELETE',
      headers: { host: 'example.com' },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'max-age=3600' },
    };
    const policyPut = createPolicy(reqPut, res);
    const policyDelete = createPolicy(reqDelete, res);
    assert.equal(policyPut.storable(), false);
    assert.equal(policyDelete.storable(), false);
  }

  // 8. storable returns false for private response in a default shared cache
  {
    const res = {
      status: 200,
      headers: { 'cache-control': 'private, max-age=3600' },
    };
    const policyShared = createPolicy(baseReq, res, { shared: true });
    assert.equal(policyShared.storable(), false);
  }

  // 9. storable returns true for private response in a non-shared private cache
  {
    const res = {
      status: 200,
      headers: { 'cache-control': 'private, max-age=3600' },
    };
    const policyPrivate = createPolicy(baseReq, res, { shared: false });
    assert.equal(policyPrivate.storable(), true);
    assert.equal(isStorable(policyPrivate), true);
  }

  // 10. storable returns false for authenticated request in shared cache without public directive
  {
    const reqAuth = {
      url: '/api/resource',
      method: 'GET',
      headers: {
        host: 'example.com',
        authorization: 'Bearer token-12345',
      },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'max-age=3600' },
    };
    const policyAuthShared = createPolicy(reqAuth, res, { shared: true });
    assert.equal(policyAuthShared.storable(), false);
  }

  // 11. storable returns true for authenticated request in shared cache with public directive
  {
    const reqAuth = {
      url: '/api/resource',
      method: 'GET',
      headers: {
        host: 'example.com',
        authorization: 'Bearer token-12345',
      },
    };
    const res = {
      status: 200,
      headers: { 'cache-control': 'public, max-age=3600' },
    };
    const policyAuthPublic = createPolicy(reqAuth, res, { shared: true });
    assert.equal(policyAuthPublic.storable(), true);
    assert.equal(isStorable(policyAuthPublic), true);
  }

  // 12. storable returns false for status code 302 without explicit expiration
  {
    const res302 = {
      status: 302,
      headers: { location: '/new-location' },
    };
    const policy302 = createPolicy(baseReq, res302);
    assert.equal(policy302.storable(), false);
  }

  // 13. storable returns true for status code 302 with explicit max-age expiration
  {
    const res302Explicit = {
      status: 302,
      headers: {
        location: '/new-location',
        'cache-control': 'max-age=300',
      },
    };
    const policy302Explicit = createPolicy(baseReq, res302Explicit);
    assert.equal(policy302Explicit.storable(), true);
    assert.equal(isStorable(policy302Explicit), true);
  }

  // 14. storable returns false for status code 502 not understood by cache
  {
    const res502 = {
      status: 502,
      headers: { 'cache-control': 'max-age=3600' },
    };
    const policy502 = createPolicy(baseReq, res502);
    assert.equal(policy502.storable(), false);
  }

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

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