tinyrainbow 1.2.0: createColors

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 tinyrainbow.createColors in pkg:npm/tinyrainbow@1.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyrainbow@1.2.0
Demonstrate these symbols/APIs:
  - tinyrainbow.createColors

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:cbaa7c6df4e9bb41b3c9568c8e9dc24f9b04c7b87fe07abe979b68c38fff252d","contract":["createColors creates a color formatter instance with an isColorSupported flag","createColors honors NO_COLOR environment variable to disable color formatting","createColors honors FORCE_COLOR environment variable to enable color formatting","createColors detects TTY terminal support when FORCE_COLOR is unset","color instance provides standard and bright foreground color formatters with matching open and close codes","color instance provides standard and bright background color formatters with matching open and close codes","color instance provides text modifier formatters with matching open and close codes","color formatters properly restore surrounding ANSI styles when nested","disabled color instance returns input as string without ANSI escape sequences"],"goal":"verify tinyrainbow.createColors in pkg:npm/tinyrainbow@1.2.0","kind":"HOW","packages":["pkg:npm/tinyrainbow@1.2.0"],"schemaVersion":1,"symbols":["tinyrainbow.createColors"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/tinyrainbow@1.2.0"],"schemaVersion":1,"subject":"pkg:npm/tinyrainbow@1.2.0","symbols":["tinyrainbow.createColors"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyrainbow-create-colors",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyrainbow-create-colors",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tinyrainbow": "1.2.0"
      }
    },
    "node_modules/tinyrainbow": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-1.2.0.tgz",
      "integrity": "sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-tinyrainbow-create-colors",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tinyrainbow": "1.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify tinyrainbow.createColors in pkg:npm/tinyrainbow@1.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyrainbow@1.2.0"
  ],
  "symbols": [
    "tinyrainbow.createColors"
  ]
}

import { createColors } from 'tinyrainbow';

/**
 * Creates and returns a tinyrainbow color formatter instance.
 * @param {boolean} [isTTY] - Explicit TTY availability flag.
 * @returns {object} Formatter instance containing color functions and isColorSupported.
 */
export function initColors(isTTY) {
  return createColors(isTTY);
}

/**
 * Formats a message with a foreground color using a given color instance.
 * @param {object} colors - Formatter instance from createColors.
 * @param {string} colorName - Name of foreground color (e.g. 'red', 'green', 'blue').
 * @param {unknown} text - Text or value to format.
 * @returns {string} Formatted string.
 */
export function formatColor(colors, colorName, text) {
  const formatter = colors[colorName];
  if (typeof formatter !== 'function') {
    throw new Error(`Unknown color formatter: ${colorName}`);
  }
  return formatter(text);
}

/**
 * Formats a message with a background color using a given color instance.
 * @param {object} colors - Formatter instance from createColors.
 * @param {string} bgColorName - Name of background color (e.g. 'bgRed', 'bgGreen').
 * @param {unknown} text - Text or value to format.
 * @returns {string} Formatted string.
 */
export function formatBgColor(colors, bgColorName, text) {
  const formatter = colors[bgColorName];
  if (typeof formatter !== 'function') {
    throw new Error(`Unknown background formatter: ${bgColorName}`);
  }
  return formatter(text);
}

/**
 * Formats a message with a text modifier using a given color instance.
 * @param {object} colors - Formatter instance from createColors.
 * @param {string} modifierName - Name of modifier (e.g. 'bold', 'dim', 'italic').
 * @param {unknown} text - Text or value to format.
 * @returns {string} Formatted string.
 */
export function formatModifier(colors, modifierName, text) {
  const formatter = colors[modifierName];
  if (typeof formatter !== 'function') {
    throw new Error(`Unknown modifier: ${modifierName}`);
  }
  return formatter(text);
}

/**
 * Combines modifier, foreground, and background colors on text.
 * @param {object} colors - Formatter instance from createColors.
 * @param {unknown} text - Target text.
 * @param {object} [options]
 * @param {string} [options.color]
 * @param {string} [options.bgColor]
 * @param {string} [options.modifier]
 * @returns {string} Formatted text.
 */
export function formatCompound(colors, text, options = {}) {
  let result = text;
  if (options.color) {
    result = formatColor(colors, options.color, result);
  }
  if (options.bgColor) {
    result = formatBgColor(colors, options.bgColor, result);
  }
  if (options.modifier) {
    result = formatModifier(colors, options.modifier, result);
  }
  return result;
}

export { createColors };

import assert from 'node:assert';
import {
  createColors,
  initColors,
  formatColor,
  formatBgColor,
  formatModifier,
  formatCompound,
} from '../src/index.mjs';

const originalEnv = { ...process.env };

function restoreEnv() {
  for (const key of Object.keys(process.env)) {
    if (!(key in originalEnv)) {
      delete process.env[key];
    }
  }
  Object.assign(process.env, originalEnv);
}

try {
  // 1. createColors creates a color formatter instance with an isColorSupported flag
  const defaultInstance = createColors();
  assert(defaultInstance && typeof defaultInstance === 'object', 'createColors must return an object');
  assert(typeof defaultInstance.isColorSupported === 'boolean', 'isColorSupported must be a boolean');
  assert.strictEqual(typeof defaultInstance.red, 'function', 'instance must provide red formatter function');
  assert.strictEqual(typeof defaultInstance.bold, 'function', 'instance must provide bold formatter function');

  const wrappedInstance = initColors(true);
  assert(wrappedInstance && typeof wrappedInstance === 'object', 'initColors must return an object');

  // 2. createColors honors NO_COLOR environment variable to disable color formatting
  process.env.NO_COLOR = '1';
  delete process.env.FORCE_COLOR;
  const noColorInstance = createColors(true);
  assert.strictEqual(noColorInstance.isColorSupported, false, 'NO_COLOR must disable isColorSupported');
  assert.strictEqual(noColorInstance.red('hello'), 'hello', 'formatter must return raw text when disabled');
  assert.strictEqual(noColorInstance.red.open, '', 'open code must be empty when disabled');
  assert.strictEqual(noColorInstance.red.close, '', 'close code must be empty when disabled');

  // 3. createColors honors FORCE_COLOR environment variable to enable color formatting
  delete process.env.NO_COLOR;
  process.env.FORCE_COLOR = '1';
  const forceColorInstance = createColors(false);
  assert.strictEqual(forceColorInstance.isColorSupported, true, 'FORCE_COLOR must enable isColorSupported');
  assert.strictEqual(forceColorInstance.red('hello'), '\u001B[31mhello\u001B[39m');
  assert.strictEqual(forceColorInstance.red.open, '\u001B[31m');
  assert.strictEqual(forceColorInstance.red.close, '\u001B[39m');

  // 4. createColors detects TTY terminal support when FORCE_COLOR is unset
  delete process.env.NO_COLOR;
  delete process.env.FORCE_COLOR;
  delete process.env.CI;
  process.env.TERM = 'xterm-256color';

  const ttySupported = createColors(true);
  assert.strictEqual(ttySupported.isColorSupported, true, 'isColorSupported must be true for TTY with xterm');

  if (process.platform !== 'win32') {
    const ttyUnsupported = createColors(false);
    assert.strictEqual(ttyUnsupported.isColorSupported, false, 'isColorSupported must be false when isTTY is false on non-windows without CI');
  }

  process.env.FORCE_COLOR = '1';
  const c = createColors(true);

  // 5. color instance provides standard and bright foreground color formatters with matching open and close codes
  const standardForegrounds = {
    black: '\u001B[30m',
    red: '\u001B[31m',
    green: '\u001B[32m',
    yellow: '\u001B[33m',
    blue: '\u001B[34m',
    magenta: '\u001B[35m',
    cyan: '\u001B[36m',
    white: '\u001B[37m',
    gray: '\u001B[90m',
  };

  for (const [name, openCode] of Object.entries(standardForegrounds)) {
    const fn = c[name];
    assert.strictEqual(typeof fn, 'function', `Missing foreground function: ${name}`);
    assert.strictEqual(fn.open, openCode, `${name} open code mismatch`);
    assert.strictEqual(fn.close, '\u001B[39m', `${name} close code mismatch`);
    assert.strictEqual(fn('text'), `${openCode}text\u001B[39m`);
    assert.strictEqual(formatColor(c, name, 'text'), `${openCode}text\u001B[39m`);
  }

  const brightForegrounds = {
    blackBright: '\u001B[90m',
    redBright: '\u001B[91m',
    greenBright: '\u001B[92m',
    yellowBright: '\u001B[93m',
    blueBright: '\u001B[94m',
    magentaBright: '\u001B[95m',
    cyanBright: '\u001B[96m',
    whiteBright: '\u001B[97m',
  };

  for (const [name, openCode] of Object.entries(brightForegrounds)) {
    const fn = c[name];
    assert.strictEqual(typeof fn, 'function', `Missing bright foreground function: ${name}`);
    assert.strictEqual(fn.open, openCode, `${name} open code mismatch`);
    assert.strictEqual(fn.close, '\u001B[39m', `${name} close code mismatch`);
    assert.strictEqual(fn('text'), `${openCode}text\u001B[39m`);
    assert.strictEqual(formatColor(c, name, 'text'), `${openCode}text\u001B[39m`);
  }

  // 6. color instance provides standard and bright background color formatters with matching open and close codes
  const standardBackgrounds = {
    bgBlack: '\u001B[40m',
    bgRed: '\u001B[41m',
    bgGreen: '\u001B[42m',
    bgYellow: '\u001B[43m',
    bgBlue: '\u001B[44m',
    bgMagenta: '\u001B[45m',
    bgCyan: '\u001B[46m',
    bgWhite: '\u001B[47m',
  };

  for (const [name, openCode] of Object.entries(standardBackgrounds)) {
    const fn = c[name];
    assert.strictEqual(typeof fn, 'function', `Missing background function: ${name}`);
    assert.strictEqual(fn.open, openCode, `${name} open code mismatch`);
    assert.strictEqual(fn.close, '\u001B[49m', `${name} close code mismatch`);
    assert.strictEqual(fn('text'), `${openCode}text\u001B[49m`);
    assert.strictEqual(formatBgColor(c, name, 'text'), `${openCode}text\u001B[49m`);
  }

  const brightBackgrounds = {
    bgBlackBright: '\u001B[100m',
    bgRedBright: '\u001B[101m',
    bgGreenBright: '\u001B[102m',
    bgYellowBright: '\u001B[103m',
    bgBlueBright: '\u001B[104m',
    bgMagentaBright: '\u001B[105m',
    bgCyanBright: '\u001B[106m',
    bgWhiteBright: '\u001B[107m',
  };

  for (const [name, openCode] of Object.entries(brightBackgrounds)) {
    const fn = c[name];
    assert.strictEqual(typeof fn, 'function', `Missing bright background function: ${name}`);
    assert.strictEqual(fn.open, openCode, `${name} open code mismatch`);
    assert.strictEqual(fn.close, '\u001B[49m', `${name} close code mismatch`);
    assert.strictEqual(fn('text'), `${openCode}text\u001B[49m`);
    assert.strictEqual(formatBgColor(c, name, 'text'), `${openCode}text\u001B[49m`);
  }

  // 7. color instance provides text modifier formatters with matching open and close codes
  const modifiers = {
    reset: { open: '\u001B[0m', close: '\u001B[0m' },
    bold: { open: '\u001B[1m', close: '\u001B[22m' },
    dim: { open: '\u001B[2m', close: '\u001B[22m' },
    italic: { open: '\u001B[3m', close: '\u001B[23m' },
    underline: { open: '\u001B[4m', close: '\u001B[24m' },
    inverse: { open: '\u001B[7m', close: '\u001B[27m' },
    hidden: { open: '\u001B[8m', close: '\u001B[28m' },
    strikethrough: { open: '\u001B[9m', close: '\u001B[29m' },
  };

  for (const [name, expected] of Object.entries(modifiers)) {
    const fn = c[name];
    assert.strictEqual(typeof fn, 'function', `Missing modifier function: ${name}`);
    assert.strictEqual(fn.open, expected.open, `${name} open mismatch`);
    assert.strictEqual(fn.close, expected.close, `${name} close mismatch`);
    assert.strictEqual(fn('mod'), `${expected.open}mod${expected.close}`);
    assert.strictEqual(formatModifier(c, name, 'mod'), `${expected.open}mod${expected.close}`);
  }

  // 8. color formatters properly restore surrounding ANSI styles when nested
  const nestedColor = c.red(`a ${c.blue('b')} c`);
  assert.strictEqual(nestedColor, '\u001B[31ma \u001B[34mb\u001B[31m c\u001B[39m');

  const nestedBold = c.bold(`a ${c.bold('b')} c`);
  assert.strictEqual(nestedBold, '\u001B[1ma \u001B[1mb\u001B[22m\u001B[1m c\u001B[22m');

  const compound = formatCompound(c, 'hello', { color: 'green', bgColor: 'bgBlack', modifier: 'bold' });
  assert.strictEqual(compound, '\u001B[1m\u001B[40m\u001B[32mhello\u001B[39m\u001B[49m\u001B[22m');

  assert.throws(() => formatColor(c, 'invalidColor', 'x'), /Unknown color formatter/);
  assert.throws(() => formatBgColor(c, 'invalidBg', 'x'), /Unknown background formatter/);
  assert.throws(() => formatModifier(c, 'invalidMod', 'x'), /Unknown modifier/);

  // 9. disabled color instance returns input as string without ANSI escape sequences
  process.env.NO_COLOR = '1';
  delete process.env.FORCE_COLOR;
  const off = createColors(true);
  assert.strictEqual(off.red('test'), 'test');
  assert.strictEqual(off.bgBlue('test'), 'test');
  assert.strictEqual(off.bold('test'), 'test');
  assert.strictEqual(formatCompound(off, 'test', { color: 'red', bgColor: 'bgBlue', modifier: 'bold' }), 'test');
  assert.strictEqual(off.red(123), '123');

  console.log('All contract assertions for tinyrainbow.createColors passed successfully.');
} finally {
  restoreEnv();
}