pvutils 1.1.5

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 pkg:npm/pvutils@1.1.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pvutils@1.1.5

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:6caaaadd7c401aa318aed809d66a2f12a70f5855447344f95930406a1b50309f","contract":["stringToArrayBuffer and arrayBufferToString convert between strings and ArrayBuffers","bufferToHexCodes converts ArrayBuffers to hexadecimal strings with optional offset, length, and spacing","utilConcatBuf concatenates multiple ArrayBuffers into a single continuous buffer","isEqualBuffer compares two ArrayBuffers and returns true if their byte contents match","toBase64 and fromBase64 encode and decode strings using standard and URL-safe Base64","padNumber pads numbers with leading zeros to the specified width","getParametersValue extracts property values from parameter objects with fallback defaults"],"goal":"verify pkg:npm/pvutils@1.1.5","kind":"HOW","packages":["pkg:npm/pvutils@1.1.5"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/pvutils@1.1.5"],"schemaVersion":1,"subject":"pkg:npm/pvutils@1.1.5","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-pvutils",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-pvutils",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "pvutils": "1.1.5"
      }
    },
    "node_modules/pvutils": {
      "version": "1.1.5",
      "resolved": "https://registry.npmjs.org/pvutils/-/pvutils-1.1.5.tgz",
      "integrity": "sha512-KTqnxsgGiQ6ZAzZCVlJH5eOjSnvlyEgx1m8bkRJfOhmGRqfo5KLvmAlACQkrjEtOQ4B7wF9TdSLIs9O90MX9xA==",
      "license": "MIT",
      "engines": {
        "node": ">=16.0.0"
      }
    }
  }
}

{
  "name": "sample-pvutils",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for pvutils",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "pvutils": "1.1.5"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/pvutils@1.1.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pvutils@1.1.5"
  ]
}

const pvutils = require('pvutils');

/**
 * Converts a string into an ArrayBuffer.
 * @param {string} str - Input text string.
 * @returns {ArrayBuffer} Converted ArrayBuffer.
 */
function textToBuffer(str) {
  return pvutils.stringToArrayBuffer(str);
}

/**
 * Converts an ArrayBuffer into a string.
 * @param {ArrayBuffer} buffer - Input ArrayBuffer.
 * @returns {string} Decoded string.
 */
function bufferToText(buffer) {
  return pvutils.arrayBufferToString(buffer);
}

/**
 * Converts an ArrayBuffer to a hex string.
 * @param {ArrayBuffer} buffer - Input ArrayBuffer.
 * @param {number} [offset=0] - Starting byte offset.
 * @param {number} [length] - Number of bytes to read.
 * @param {boolean} [insertSpace=false] - Whether to insert spaces between bytes.
 * @returns {string} Hexadecimal string.
 */
function toHexString(buffer, offset = 0, length = buffer.byteLength, insertSpace = false) {
  return pvutils.bufferToHexCodes(buffer, offset, length, insertSpace);
}

/**
 * Concatenates multiple ArrayBuffers into one contiguous ArrayBuffer.
 * @param {...ArrayBuffer} buffers - Buffers to concatenate.
 * @returns {ArrayBuffer} Concatenated ArrayBuffer.
 */
function concatBuffers(...buffers) {
  return pvutils.utilConcatBuf(...buffers);
}

/**
 * Compares two ArrayBuffers for equality.
 * @param {ArrayBuffer} buf1 - First buffer.
 * @param {ArrayBuffer} buf2 - Second buffer.
 * @returns {boolean} True if contents match.
 */
function areBuffersEqual(buf1, buf2) {
  return pvutils.isEqualBuffer(buf1, buf2);
}

/**
 * Encodes a string into Base64 format.
 * @param {string} input - Input string.
 * @param {boolean} [useUrl=false] - Use URL-safe Base64 template.
 * @param {boolean} [skipPadding=false] - Skip Base64 padding '='.
 * @returns {string} Base64 encoded string.
 */
function encodeBase64(input, useUrl = false, skipPadding = false) {
  return pvutils.toBase64(input, useUrl, skipPadding);
}

/**
 * Decodes a Base64 string.
 * @param {string} input - Base64 encoded string.
 * @param {boolean} [useUrl=false] - Use URL-safe template.
 * @returns {string} Decoded plain string.
 */
function decodeBase64(input, useUrl = false) {
  return pvutils.fromBase64(input, useUrl);
}

/**
 * Pads a number with leading zeros.
 * @param {number} num - Number to pad.
 * @param {number} length - Desired string length.
 * @returns {string} Padded number string.
 */
function formatNumber(num, length) {
  return pvutils.padNumber(num, length);
}

/**
 * Safely extracts a named parameter with default fallback.
 * @param {Record<string, any>} params - Parameter object.
 * @param {string} key - Property name.
 * @param {any} fallback - Default value if not found.
 * @returns {any} Property value or fallback.
 */
function getParam(params, key, fallback) {
  return pvutils.getParametersValue(params, key, fallback);
}

module.exports = {
  pvutils,
  textToBuffer,
  bufferToText,
  toHexString,
  concatBuffers,
  areBuffersEqual,
  encodeBase64,
  decodeBase64,
  formatNumber,
  getParam
};

const assert = require('node:assert');
const pvutils = require('pvutils');
const {
  textToBuffer,
  bufferToText,
  toHexString,
  concatBuffers,
  areBuffersEqual,
  encodeBase64,
  decodeBase64,
  formatNumber,
  getParam
} = require('../src/index.js');

// 1. stringToArrayBuffer and arrayBufferToString convert between strings and ArrayBuffers
const sampleText = 'Verification test payload for pvutils';
const buf = textToBuffer(sampleText);
assert.ok(buf instanceof ArrayBuffer, 'textToBuffer must return an ArrayBuffer');
assert.strictEqual(buf.byteLength, sampleText.length, 'buffer length must match text length');
assert.strictEqual(bufferToText(buf), sampleText, 'bufferToText must decode back to original text');

const emptyBuf = textToBuffer('');
assert.strictEqual(emptyBuf.byteLength, 0, 'empty string produces 0-length buffer');
assert.strictEqual(bufferToText(emptyBuf), '', 'empty buffer decodes to empty string');

// Direct pvutils export check
assert.strictEqual(typeof pvutils.stringToArrayBuffer, 'function');
assert.strictEqual(typeof pvutils.arrayBufferToString, 'function');

// 2. bufferToHexCodes converts ArrayBuffers to hexadecimal strings with optional offset, length, and spacing
const hexSample = textToBuffer('Hello');
assert.strictEqual(toHexString(hexSample), '48656C6C6F', 'full buffer to hex codes');
assert.strictEqual(toHexString(hexSample, 1, 3), '656C6C', 'offset and length slice to hex');
assert.strictEqual(toHexString(hexSample, 0, 5, true), '48 65 6C 6C 6F', 'insert spaces between hex codes');

// 3. utilConcatBuf concatenates multiple ArrayBuffers into a single continuous buffer
const chunk1 = textToBuffer('Alpha');
const chunk2 = textToBuffer('Beta');
const chunk3 = textToBuffer('Gamma');
const combined = concatBuffers(chunk1, chunk2, chunk3);
assert.ok(combined instanceof ArrayBuffer, 'concatenated result must be an ArrayBuffer');
assert.strictEqual(combined.byteLength, 14, 'concatenated buffer byteLength must match total');
assert.strictEqual(bufferToText(combined), 'AlphaBetaGamma', 'concatenated content must match joined string');

// 4. isEqualBuffer compares two ArrayBuffers and returns true if their byte contents match
const bufA = textToBuffer('ConsistentData');
const bufB = textToBuffer('ConsistentData');
const bufC = textToBuffer('DifferentData');
assert.strictEqual(areBuffersEqual(bufA, bufB), true, 'identical buffers must return true');
assert.strictEqual(areBuffersEqual(bufA, bufC), false, 'different buffers must return false');
assert.strictEqual(areBuffersEqual(bufA, combined), false, 'buffers of different length must return false');

// 5. toBase64 and fromBase64 encode and decode strings using standard and URL-safe Base64
const plainString = 'Standard and URL-safe Base64 payload string';
const encodedB64 = encodeBase64(plainString);
assert.strictEqual(typeof encodedB64, 'string', 'encodeBase64 must return a string');
assert.strictEqual(decodeBase64(encodedB64), plainString, 'decodeBase64 must roundtrip properly');

const urlUnsafeString = 'Subject?value=1&data=true+more';
const urlB64 = encodeBase64(urlUnsafeString, true, true);
assert.strictEqual(urlB64.includes('+'), false, 'URL-safe base64 must not contain "+"');
assert.strictEqual(urlB64.includes('/'), false, 'URL-safe base64 must not contain "/"');
assert.strictEqual(urlB64.includes('='), false, 'Skipped padding must not contain "="');

// 6. padNumber pads numbers with leading zeros to the specified width
assert.strictEqual(formatNumber(7, 4), '0007', 'pad single digit to length 4');
assert.strictEqual(formatNumber(42, 5), '00042', 'pad double digit to length 5');
assert.strictEqual(formatNumber(1234, 4), '1234', 'number matching target length remains unchanged');
assert.strictEqual(formatNumber(99999, 3), '', 'number exceeding target length returns empty string');

// 7. getParametersValue extracts property values from parameter objects with fallback defaults
const config = { maxRetries: 5, debug: false, label: 'test-runner' };
assert.strictEqual(getParam(config, 'maxRetries', 1), 5, 'existing numeric param');
assert.strictEqual(getParam(config, 'debug', true), false, 'existing boolean false param should not be overridden');
assert.strictEqual(getParam(config, 'label', 'default'), 'test-runner', 'existing string param');
assert.strictEqual(getParam(config, 'missingKey', 'fallbackValue'), 'fallbackValue', 'missing param returns default');

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