pac-resolver 7.0.1: PacResolver

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 PacResolver in pkg:npm/pac-resolver@7.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pac-resolver@7.0.1
Demonstrate these symbols/APIs:
  - PacResolver
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:3d43b24680d7397a9bd135d672e5cd801b9b6bf9e7d9531729eb2233d1824dcf","constraints":{"executionContext":"node"},"contract":["PacResolver instantiates a resolver instance wrapping createPacResolver for PAC scripts","PacResolver.resolve evaluates PAC logic using built-in sandbox helpers to return proxy directives","createPacResolver generates an asynchronous FindProxyForURL function from string and Buffer PAC scripts","createPacResolver supports custom sandbox functions supplied in options","FindProxyForURL rejects with TypeError when host cannot be determined"],"goal":"verify PacResolver in pkg:npm/pac-resolver@7.0.1","kind":"HOW","packages":["pkg:npm/pac-resolver@7.0.1"],"schemaVersion":1,"symbols":["PacResolver"]},"contractCommand":["node","test/contract.cjs"],"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/pac-resolver@7.0.1"],"schemaVersion":1,"subject":"pkg:npm/pac-resolver@7.0.1","symbols":["PacResolver"],"verifierAdapter":"node-typescript@1"}

'use strict';

const { createPacResolver, sandbox } = require('pac-resolver');

/**
 * PacResolver wraps the createPacResolver factory into a class interface.
 */
class PacResolver {
  /**
   * @param {import('@tootallnate/quickjs-emscripten').QuickJSWASMModule} qjs
   * @param {string | Buffer} script
   * @param {import('pac-resolver').PacResolverOptions} [options]
   */
  constructor(qjs, script, options = {}) {
    if (!qjs) {
      throw new TypeError('QuickJS WASM module instance is required');
    }
    if (!script) {
      throw new TypeError('PAC script is required');
    }
    this.qjs = qjs;
    this.script = script;
    this.options = options;
    this.resolver = createPacResolver(qjs, script, options);
  }

  /**
   * Resolves the proxy for the given URL and optional host override.
   * @param {string | URL} url
   * @param {string} [host]
   * @returns {Promise<string>}
   */
  async resolve(url, host) {
    return this.resolver(url, host);
  }
}

module.exports = {
  PacResolver,
  createPacResolver,
  sandbox
};

{
  "name": "sample-pac-resolver",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-pac-resolver",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@tootallnate/quickjs-emscripten": "^0.23.0",
        "pac-resolver": "7.0.1"
      }
    },
    "node_modules/@tootallnate/quickjs-emscripten": {
      "version": "0.23.0",
      "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz",
      "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==",
      "license": "MIT"
    },
    "node_modules/ast-types": {
      "version": "0.13.4",
      "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.13.4.tgz",
      "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==",
      "license": "MIT",
      "dependencies": {
        "tslib": "^2.0.1"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/degenerator": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/degenerator/-/degenerator-5.0.1.tgz",
      "integrity": "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==",
      "license": "MIT",
      "dependencies": {
        "ast-types": "^0.13.4",
        "escodegen": "^2.1.0",
        "esprima": "^4.0.1"
      },
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/escodegen": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz",
      "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "esprima": "^4.0.1",
        "estraverse": "^5.2.0",
        "esutils": "^2.0.2"
      },
      "bin": {
        "escodegen": "bin/escodegen.js",
        "esgenerate": "bin/esgenerate.js"
      },
      "engines": {
        "node": ">=6.0"
      },
      "optionalDependencies": {
        "source-map": "~0.6.1"
      }
    },
    "node_modules/esprima": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
      "license": "BSD-2-Clause",
      "bin": {
        "esparse": "bin/esparse.js",
        "esvalidate": "bin/esvalidate.js"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/estraverse": {
      "version": "5.3.0",
      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=4.0"
      }
    },
    "node_modules/esutils": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/netmask": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.1.1.tgz",
      "integrity": "sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4.0"
      }
    },
    "node_modules/pac-resolver": {
      "version": "7.0.1",
      "resolved": "https://registry.npmjs.org/pac-resolver/-/pac-resolver-7.0.1.tgz",
      "integrity": "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==",
      "license": "MIT",
      "dependencies": {
        "degenerator": "^5.0.0",
        "netmask": "^2.0.2"
      },
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/source-map": {
      "version": "0.6.1",
      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
      "license": "BSD-3-Clause",
      "optional": true,
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
      "license": "0BSD"
    }
  }
}

{
  "name": "sample-pac-resolver",
  "version": "1.0.0",
  "private": true,
  "description": "verify PacResolver in pkg:npm/pac-resolver@7.0.1",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "@tootallnate/quickjs-emscripten": "^0.23.0",
    "pac-resolver": "7.0.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify PacResolver in pkg:npm/pac-resolver@7.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pac-resolver@7.0.1"
  ],
  "symbols": [
    "PacResolver"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

'use strict';

const assert = require('assert');
const { getQuickJS } = require('@tootallnate/quickjs-emscripten');
const { PacResolver, createPacResolver, sandbox } = require('../index.js');

async function run() {
  // 1. Export verification
  assert.strictEqual(typeof PacResolver, 'function', 'PacResolver class must be exported');
  assert.strictEqual(typeof createPacResolver, 'function', 'createPacResolver must be exported');
  assert.strictEqual(typeof sandbox, 'object', 'sandbox must be exported as an object');

  // 2. Built-in sandbox functions verification
  const expectedSandboxFunctions = [
    'alert',
    'dateRange',
    'dnsDomainIs',
    'dnsDomainLevels',
    'dnsResolve',
    'isInNet',
    'isPlainHostName',
    'isResolvable',
    'localHostOrDomainIs',
    'myIpAddress',
    'shExpMatch',
    'timeRange',
    'weekdayRange'
  ];
  for (const fnName of expectedSandboxFunctions) {
    assert.strictEqual(typeof sandbox[fnName], 'function', `sandbox.${fnName} must be a function`);
  }

  // 3. Initialize QuickJS WASM module
  const qjs = await getQuickJS();
  assert(qjs, 'QuickJS WASM module must be initialized');

  // 4. Test PacResolver class with standard PAC script
  const pacScript = `
    function FindProxyForURL(url, host) {
      if (isPlainHostName(host)) {
        return "DIRECT";
      }
      if (dnsDomainIs(host, ".internal.example.com")) {
        return "PROXY proxy-internal.example.com:3128";
      }
      if (shExpMatch(host, "*.secure.example.com")) {
        return "PROXY proxy-secure.example.com:8443";
      }
      if (isInNet(host, "10.0.0.0", "255.0.0.0")) {
        return "PROXY proxy-corp.example.com:8080";
      }
      return "DIRECT";
    }
  `;

  const pacInstance = new PacResolver(qjs, pacScript);
  assert(pacInstance instanceof PacResolver, 'pacInstance must be an instance of PacResolver');

  // Test isPlainHostName
  const plainResult = await pacInstance.resolve('http://localhost/api');
  assert.strictEqual(plainResult, 'DIRECT', 'Plain host should resolve to DIRECT');

  // Test dnsDomainIs
  const internalResult = await pacInstance.resolve('http://service.internal.example.com/data');
  assert.strictEqual(internalResult, 'PROXY proxy-internal.example.com:3128', 'Domain match should resolve to internal proxy');

  // Test shExpMatch
  const secureResult = await pacInstance.resolve('https://portal.secure.example.com/app');
  assert.strictEqual(secureResult, 'PROXY proxy-secure.example.com:8443', 'Wildcard pattern should resolve to secure proxy');

  // Test isInNet with host override
  const subnetResult = await pacInstance.resolve('http://example.com/status', '10.10.0.1');
  assert.strictEqual(subnetResult, 'PROXY proxy-corp.example.com:8080', 'Subnet match should resolve to corp proxy');

  // Test fallback DIRECT
  const fallbackResult = await pacInstance.resolve('http://example.com/index.html');
  assert.strictEqual(fallbackResult, 'DIRECT', 'Unmatched host should fallback to DIRECT');

  // 5. Test createPacResolver with Buffer input
  const bufferPac = Buffer.from(`
    function FindProxyForURL(url, host) {
      if (host === "buffer.example.com") {
        return "PROXY proxy-buffer.example.com:8080";
      }
      return "DIRECT";
    }
  `);
  const bufferResolver = createPacResolver(qjs, bufferPac);
  assert.strictEqual(await bufferResolver('http://buffer.example.com/'), 'PROXY proxy-buffer.example.com:8080');
  assert.strictEqual(await bufferResolver('http://example.com/'), 'DIRECT');

  // 6. Test custom sandbox functions passed in options
  const customPac = `
    function FindProxyForURL(url, host) {
      if (isCustomTarget(host)) {
        return "PROXY custom-proxy.example.com:9000";
      }
      return "DIRECT";
    }
  `;
  const customResolver = createPacResolver(qjs, customPac, {
    sandbox: {
      isCustomTarget: (host) => host.startsWith('custom-')
    }
  });
  assert.strictEqual(await customResolver('http://custom-app.example.com/'), 'PROXY custom-proxy.example.com:9000');
  assert.strictEqual(await customResolver('http://other.example.com/'), 'DIRECT');

  // 7. Test WHATWG URL instance input and host override
  const urlObj = new URL('http://example.com/path');
  const urlResult = await bufferResolver(urlObj);
  assert.strictEqual(urlResult, 'DIRECT');

  const overrideResult = await bufferResolver(urlObj, 'buffer.example.com');
  assert.strictEqual(overrideResult, 'PROXY proxy-buffer.example.com:8080');

  // 8. Test error handling for invalid input / empty URL
  await assert.rejects(
    async () => {
      await bufferResolver('');
    },
    {
      name: 'TypeError'
    },
    'Should reject with TypeError when host cannot be determined'
  );

  // 9. Constructor argument validation
  assert.throws(() => {
    new PacResolver(null, 'function FindProxyForURL() {}');
  }, /^TypeError: QuickJS WASM module instance is required/);

  assert.throws(() => {
    new PacResolver(qjs, '');
  }, /^TypeError: PAC script is required/);

  console.log('Contract tests passed successfully.');
}

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