pvutils 1.2.0

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.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pvutils@1.2.0
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:deaa8f9e3b94aa9d7c9d15c3d920067eea2ca7678492f13b6543065e45dec9aa","constraints":{"executionContext":"node"},"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","getUTCDate creates a UTC date from a local date adjusted by timezone offset","nearestPowerOf2 calculates the nearest power of 2 exponent for a given length"],"goal":"verify pkg:npm/pvutils@1.2.0","kind":"HOW","packages":["pkg:npm/pvutils@1.2.0"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"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/pvutils@1.2.0"],"schemaVersion":1,"subject":"pkg:npm/pvutils@1.2.0","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.2.0"
      }
    },
    "node_modules/pvutils": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/pvutils/-/pvutils-1.2.0.tgz",
      "integrity": "sha512-BbubeCEyTuQjVMakvJQ/Sxbc93F2pwmbsxONT/ZRrwU7Ua38d8unYTwXpTVLAKJ4BDuH9IGztCjQcd/N/39Dvg==",
      "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.2.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/pvutils@1.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pvutils@1.2.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

/**
 * Creates a UTC date from a local date adjusted by timezone offset.
 * @param {Date} date - Local date.
 * @returns {Date} UTC date.
 */
function toUTCDate(date) {
  return pvutils.getUTCDate(date);
}

/**
 * Calculates the nearest power of 2 exponent for a given length.
 * @param {number} length - Input length.
 * @returns {number} Power of 2 exponent.
 */
function getNearestPowerOf2(length) {
  return pvutils.nearestPowerOf2(length);
}

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

const assert = require('node:assert');
const pvutils = require('pvutils');
const {
  textToBuffer,
  bufferToText,
  toHexString,
  concatBuffers,
  areBuffersEqual,
  encodeBase64,
  decodeBase64,
  formatNumber,
  getParam,
  toUTCDate,
  getNearestPowerOf2
} = 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');

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

// 8. getUTCDate creates a UTC date from a local date adjusted by timezone offset
const testDate = new Date('2026-08-27T20:00:00.000Z');
const utcRes = toUTCDate(testDate);
assert.ok(utcRes instanceof Date, 'toUTCDate must return a Date');
assert.strictEqual(utcRes.getTime(), testDate.getTime() + testDate.getTimezoneOffset() * 60000);

// 9. nearestPowerOf2 calculates the nearest power of 2 exponent for a given length
assert.strictEqual(getNearestPowerOf2(8), 3, 'power of 2 for 8 is 3');
assert.strictEqual(getNearestPowerOf2(16), 4, 'power of 2 for 16 is 4');
assert.strictEqual(getNearestPowerOf2(32), 5, 'power of 2 for 32 is 5');
assert.strictEqual(getNearestPowerOf2(64), 6, 'power of 2 for 64 is 6');

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