sprintf-js 1.1.3

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/sprintf-js@1.1.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/sprintf-js@1.1.3
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:eab7c9bd03f5225034f8a41f0df062293b1486592cc9fdaccfcd751a68b46a96","constraints":{"executionContext":"node"},"contract":["sprintf formats positional arguments with %s, %d, and %x specifiers","sprintf swaps argument positions using %2$s and %1$s positional syntax","vsprintf formats template strings from an array of arguments","sprintf replaces named and nested placeholders %(user.name)s with values from a dictionary object","sprintf formats numbers with leading zeros and specified width","sprintf formats floating point numbers with specified decimal precision","sprintf formats objects into JSON strings using %j specifier","sprintf throws TypeError when a non-numeric string is provided for a numeric specifier","sprintf throws Error when mixing positional and named placeholders in a single format string"],"goal":"verify pkg:npm/sprintf-js@1.1.3","kind":"HOW","packages":["pkg:npm/sprintf-js@1.1.3"],"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/sprintf-js@1.1.3"],"schemaVersion":1,"subject":"pkg:npm/sprintf-js@1.1.3","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-sprintf-js",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-sprintf-js",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "sprintf-js": "1.1.3"
      }
    },
    "node_modules/sprintf-js": {
      "version": "1.1.3",
      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",
      "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-sprintf-js",
  "version": "1.0.0",
  "description": "verify pkg:npm/sprintf-js@1.1.3",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "sprintf-js": "1.1.3"
  },
  "license": "MIT-0"
}

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

const { sprintf, vsprintf } = require('sprintf-js');

/**
 * Formats a string using sprintf with positional arguments.
 *
 * @param {string} format - The format string with specifiers.
 * @param {...*} args - Arguments matching the specifiers.
 * @returns {string} The formatted string.
 */
function formatString(format, ...args) {
  return sprintf(format, ...args);
}

/**
 * Formats a string using sprintf with explicit positional placeholders.
 *
 * @param {string} format - The format string with indexed specifiers like %1$s, %2$s.
 * @param {...*} args - Arguments matching the indexed positions.
 * @returns {string} The formatted string.
 */
function formatPositionalIndexed(format, ...args) {
  return sprintf(format, ...args);
}

/**
 * Formats a string using vsprintf with an array of arguments.
 *
 * @param {string} format - The format string with specifiers.
 * @param {Array<*>} args - Array of arguments matching the specifiers.
 * @returns {string} The formatted string.
 */
function formatWithArray(format, args) {
  return vsprintf(format, args);
}

/**
 * Formats a string using named and nested placeholders from an object.
 *
 * @param {string} format - Format string with %(key) specifiers.
 * @param {object} params - Key-value map of parameters.
 * @returns {string} The formatted string.
 */
function formatNamed(format, params) {
  return sprintf(format, params);
}

/**
 * Formats a number with leading zeros and fixed width.
 *
 * @param {number} num - The integer number to format.
 * @param {number} width - The total target width.
 * @returns {string} The zero-padded numeric string.
 */
function formatPaddedNumber(num, width) {
  return sprintf(`%0${width}d`, num);
}

/**
 * Formats a floating-point number with specified decimal precision.
 *
 * @param {number} val - The floating point number.
 * @param {number} precision - Number of decimal places.
 * @returns {string} The formatted float string.
 */
function formatFloat(val, precision) {
  return sprintf(`%.${precision}f`, val);
}

/**
 * Formats a JavaScript object into a JSON string using %j specifier.
 *
 * @param {object} obj - The object to format as JSON.
 * @returns {string} The JSON string.
 */
function formatJson(obj) {
  return sprintf('%j', obj);
}

module.exports = {
  formatString,
  formatPositionalIndexed,
  formatWithArray,
  formatNamed,
  formatPaddedNumber,
  formatFloat,
  formatJson
};

const assert = require('assert');
const {
  formatString,
  formatPositionalIndexed,
  formatWithArray,
  formatNamed,
  formatPaddedNumber,
  formatFloat,
  formatJson
} = require('../src/index');

// 1. sprintf formats positional arguments with %s, %d, and %x specifiers
{
  const result = formatString('Item: %s, Count: %d, Hex: %x', 'Widget', 42, 255);
  assert.strictEqual(result, 'Item: Widget, Count: 42, Hex: ff');
}

// 2. sprintf swaps argument positions using %2$s and %1$s positional syntax
{
  const result = formatPositionalIndexed('%2$s, %1$s!', 'world', 'hello');
  assert.strictEqual(result, 'hello, world!');
}

// 3. vsprintf formats template strings from an array of arguments
{
  const args = ['alpha', 'beta', 100];
  const result = formatWithArray('First: %s, Second: %s, Third: %d', args);
  assert.strictEqual(result, 'First: alpha, Second: beta, Third: 100');
}

// 4. sprintf replaces named and nested placeholders %(user.name)s with values from a dictionary object
{
  const params = {
    user: {
      profile: {
        name: 'test-user'
      }
    },
    count: 3
  };
  const result = formatNamed('User %(user.profile.name)s has %(count)d items', params);
  assert.strictEqual(result, 'User test-user has 3 items');
}

// 5. sprintf formats numbers with leading zeros and specified width
{
  const result = formatPaddedNumber(42, 5);
  assert.strictEqual(result, '00042');
}

// 6. sprintf formats floating point numbers with specified decimal precision
{
  const result = formatFloat(3.14159265, 2);
  assert.strictEqual(result, '3.14');
}

// 7. sprintf formats objects into JSON strings using %j specifier
{
  const data = { status: 'ok', code: 200 };
  const result = formatJson(data);
  assert.strictEqual(result, '{"status":"ok","code":200}');
}

// 8. sprintf throws TypeError when a non-numeric string is provided for a numeric specifier
{
  assert.throws(
    () => {
      formatString('%d', 'not-a-number');
    },
    (err) => {
      return err instanceof TypeError && /expecting number/.test(err.message);
    },
    'Non-numeric argument to %d specifier must throw TypeError'
  );
}

// 9. sprintf throws Error when mixing positional and named placeholders in a single format string
{
  assert.throws(
    () => {
      formatString('%s %(name)s', 'value', { name: 'sample' });
    },
    (err) => {
      return err instanceof Error && /mixing positional and named/i.test(err.message);
    },
    'Mixing positional and named placeholders must throw Error'
  );
}

console.log('All contract assertions passed successfully.');