'use strict';
// volume-conversion.cjs -- METHOD DECK (X063), reversible volume unit conversion.
// US customary factors are the exact liter-equivalents defined in NIST Handbook 44, Appendix C
// ("General Tables of Units of Measurement"); mL, L, and the UK gallon are exact by definition.

function roundSig(x, sig) {
  if (x === 0) return { value: 0, decimals: 0 };
  const neg = x < 0;
  const ax = Math.abs(x);
  let exp = Math.floor(Math.log10(ax));
  let decimals = Math.max(sig - exp - 1, 0);
  let factor = Math.pow(10, decimals);
  let value = Math.round(ax * factor) / factor;
  const newExp = value === 0 ? exp : Math.floor(Math.log10(value));
  if (newExp !== exp) {
    decimals = Math.max(sig - newExp - 1, 0);
    factor = Math.pow(10, decimals);
    value = Math.round(ax * factor) / factor;
  }
  return { value: neg ? -value : value, decimals };
}
function fmt(x, decimals) {
  return x.toLocaleString('en-US', { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
}
function fmtSig(x, sig) {
  const r = roundSig(x, sig);
  return fmt(r.value, r.decimals);
}

// Liters per 1 unit.
const TO_LITERS = {
  mL: 0.001,
  L: 1,
  tsp: 0.00492892159375,
  tbsp: 0.01478676478125,
  fl_oz_us: 0.0295735295625,
  cup_us: 0.2365882365,
  pint_us: 0.473176473,
  quart_us: 0.946352946,
  gallon_us: 3.785411784,
  gallon_uk: 4.54609,
};
const UNITS = Object.keys(TO_LITERS);
const DISPLAY = {
  mL: 'mL', L: 'L', tsp: 'tsp', tbsp: 'tbsp', fl_oz_us: 'fl oz (US)', cup_us: 'cup (US)',
  pint_us: 'pint (US)', quart_us: 'quart (US)', gallon_us: 'gallon (US)', gallon_uk: 'gallon (UK)',
};

module.exports = {
  slug: 'volume-conversion',
  title: 'Volume conversion',
  deck_category: 'units',
  description: 'Converts a volume between metric units and US customary or UK imperial volume units.',
  inputs: [
    { name: 'value', type: 'number', unit: 'from_unit', required: true, description: 'The volume to convert' },
    { name: 'from_unit', type: 'string', required: true, description: 'Unit of the input value', enum: UNITS },
    { name: 'to_unit', type: 'string', required: true, description: 'Unit to convert into', enum: UNITS },
  ],
  outputs: [ { name: 'result', unit: 'to_unit', description: 'The converted volume' } ],
  steps: [
    'Look up the exact liter-equivalent of from_unit and of to_unit from the US customary / UK table.',
    'Convert the input to liters: liters = value * liters_per(from_unit).',
    'Convert liters to the target unit: result = liters / liters_per(to_unit).',
    'Round result to 6 significant figures.',
  ],
  constants: [
    { name: 'mL', value: 0.001, unit: 'L', source: 0 },
    { name: 'L', value: 1, unit: 'L', source: 0 },
    { name: 'tsp', value: 0.00492892159375, unit: 'L', source: 0 },
    { name: 'tbsp', value: 0.01478676478125, unit: 'L', source: 0 },
    { name: 'fl_oz_us', value: 0.0295735295625, unit: 'L', source: 0 },
    { name: 'cup_us', value: 0.2365882365, unit: 'L', source: 0 },
    { name: 'pint_us', value: 0.473176473, unit: 'L', source: 0 },
    { name: 'quart_us', value: 0.946352946, unit: 'L', source: 0 },
    { name: 'gallon_us', value: 3.785411784, unit: 'L', source: 0 },
    { name: 'gallon_uk', value: 4.54609, unit: 'L', source: 0 },
  ],
  sources: [
    { kind: 'standard', value: 'NIST Handbook 44 (2026 ed.), Appendix C, General Tables of Units of Measurement, Volume or Capacity', title: 'Specifications, Tolerances, and Other Technical Requirements for Weighing and Measuring Devices', publisher: 'National Institute of Standards and Technology', retrieved_utc: '2026-09-30T19:29:48Z', note: 'US customary units (tsp, tbsp, fl oz, cup, pint, quart, gallon) defined exactly from the US gallon = 3.785411784 L; the UK (imperial) gallon = 4.54609 L exactly per the Weights and Measures Act definition.' },
  ],
  disclaimer: null,
  questionText(inputs) {
    return `How many ${DISPLAY[inputs.to_unit]} are in ${inputs.value} ${DISPLAY[inputs.from_unit]}?`;
  },
  run(inputs) {
    const { value, from_unit, to_unit } = inputs || {};
    if (typeof value !== 'number' || !isFinite(value)) throw new Error('value must be a finite number');
    if (!TO_LITERS.hasOwnProperty(from_unit)) throw new Error('from_unit must be one of: ' + UNITS.join(', '));
    if (!TO_LITERS.hasOwnProperty(to_unit)) throw new Error('to_unit must be one of: ' + UNITS.join(', '));
    const liters = value * TO_LITERS[from_unit];
    const result = liters / TO_LITERS[to_unit];
    return { answer: `${fmtSig(result, 6)} ${DISPLAY[to_unit]}`, values: { result } };
  },
  examples: [
    { name: 'worked example', inputs: { value: 1, from_unit: 'gallon_us', to_unit: 'L' },
      expected: { answer: '3.78541 L' },
      check: 'By definition 1 US gallon = 3.785411784 L exactly; rounded to 6 significant figures is 3.78541.' },
    { name: 'test vector: cups to fluid ounces', inputs: { value: 1, from_unit: 'cup_us', to_unit: 'fl_oz_us' },
      expected: { answer: '8.00000 fl oz (US)' },
      check: 'By hand: 0.2365882365 L / 0.0295735295625 L = 8 exactly, since 1 US cup = 8 US fluid ounces by definition.' },
    { name: 'test vector: UK gallon to liters', inputs: { value: 1, from_unit: 'gallon_uk', to_unit: 'L' },
      expected: { answer: '4.54609 L' },
      check: 'By definition 1 UK (imperial) gallon = 4.54609 L exactly; already 6 significant figures.' },
  ],
};