convert_unit

Instructions

Implementation Reference

• cruncher.js:940-964 (schema)

  Input schema definition for the convert_unit tool, defining parameters: value (number), category (enum of 8 types), from (string), to (string).

  {
      name: "convert_unit",
      annotations: {
          title: "Convert Unit",
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: false,
      },
      description:
          "Convert between common units. Categories: length, weight, temperature, area, volume, time, speed, digital_storage.",
      inputSchema: {
          type: "object",
          properties: {
              value: { type: "number" },
              category: {
                  type: "string",
                  enum: ["length", "weight", "temperature", "area", "volume", "time", "speed", "digital_storage"],
              },
              from: { type: "string" },
              to: { type: "string" },
          },
          required: ["value", "category", "from", "to"],
      },
  },

• cruncher.js:85-86 (registration)

  Registration of convert_unit in the standard tool tier, making it available by default.

      "convert_unit",
  ],

• cruncher.js:153-155 (registration)

  convert_unit registered as a main-thread instant tool (no worker overhead) via MAIN_THREAD_TOOLS set.

      // Unit conversion
      "convert_unit",
  ]);

• cruncher.js:1107-1202 (helper)

  Unit conversion factor tables for 8 categories (length, weight, temperature, area, volume, time, speed, digital_storage). Each maps unit keys to their conversion factor to a base unit.

  const UNIT_CONVERSIONS = {
      // Length → meters
      length: {
          m: 1,
          km: 1000,
          cm: 0.01,
          mm: 0.001,
          um: 1e-6,
          nm: 1e-9,
          in: 0.0254,
          ft: 0.3048,
          yd: 0.9144,
          mi: 1609.344,
          nmi: 1852, // nautical mile
      },
      // Weight → kilograms
      weight: {
          kg: 1,
          g: 0.001,
          mg: 1e-6,
          ug: 1e-9,
          lb: 0.45359237,
          oz: 0.028349523125,
          st: 6.35029318, // stone
          t: 1000, // metric ton
      },
      // Temperature — special handling (not linear)
      temperature: {
          C: null,
          F: null,
          K: null,
      },
      // Area → square meters
      area: {
          m2: 1,
          km2: 1e6,
          cm2: 1e-4,
          ft2: 0.09290304,
          ac: 4046.8564224,
          ha: 1e4,
          in2: 0.00064516,
          yd2: 0.83612736,
          mi2: 2589988.110336,
      },
      // Volume → liters
      volume: {
          L: 1,
          mL: 0.001,
          m3: 1000,
          cm3: 0.001,
          gal: 3.785411784, // US gallon
          qt: 0.946352946, // US quart
          pt: 0.473176473, // US pint
          cup: 0.2365882365, // US cup
          floz: 0.029573529563, // US fluid ounce
          tbsp: 0.014786764782, // US tablespoon
          tsp: 0.004928921594, // US teaspoon
          imp_gal: 4.54609, // Imperial gallon
      },
      // Time → seconds
      time: {
          s: 1,
          ms: 0.001,
          us: 1e-6,
          ns: 1e-9,
          min: 60,
          hr: 3600,
          day: 86400,
          week: 604800,
          month: 2629746, // average month (30.44 days)
          year: 31556952, // Julian year
      },
      // Speed → meters per second
      speed: {
          "m/s": 1,
          "km/h": 1 / 3.6,
          mph: 0.44704,
          kn: 0.514444, // knots
          "ft/s": 0.3048,
          mach: 343, // at sea level, 20°C
          c: 299792458, // speed of light
      },
      // Digital storage → bytes
      digital_storage: {
          B: 1,
          KB: 1024,
          MB: 1048576,
          GB: 1073741824,
          TB: 1099511627776,
          PB: 1125899906842624,
          b: 0.125, // bits
          Kb: 128,
          Mb: 131072,
          Gb: 134217728,
      },
  };

• cruncher.js:1211-1227 (helper)

  Helper function for temperature conversion (C, F, K) which uses non-linear formulas instead of simple factor multiplication.

  const convertTemperature = (value, from, to) => {
      // Convert to Celsius first
      let celsius;
      switch (from) {
          case 'C': celsius = value; break;
          case 'F': celsius = (value - 32) * 5 / 9; break;
          case 'K': celsius = value - 273.15; break;
          default: throw new Error(`Unknown temperature unit: ${from}`);
      }
      // Convert from Celsius to target
      switch (to) {
          case 'C': return celsius;
          case 'F': return celsius * 9 / 5 + 32;
          case 'K': return celsius + 273.15;
          default: throw new Error(`Unknown temperature unit: ${to}`);
      }
  };

• cruncher.js:1907-1953 (handler)

  Main handler function for the convert_unit tool. Looks up the category in UNIT_CONVERSIONS, normalizes units case-insensitively, handles temperature specially via convertTemperature(), and returns a JSON string with the converted result.

  convert_unit: ({ value, category, from, to }) => {
      const conversions = UNIT_CONVERSIONS[category];
      if (!conversions) {
          throw new Error(`Unknown unit category: ${category}. Valid: ${Object.keys(UNIT_CONVERSIONS).join(', ')}`);
      }
  
      const fromLower = from.toLowerCase();
      const toLower = to.toLowerCase();
  
      // Normalize keys (match case-insensitively)
      const fromKey = Object.keys(conversions).find(k => k.toLowerCase() === fromLower);
      const toKey = Object.keys(conversions).find(k => k.toLowerCase() === toLower);
  
      if (!fromKey) {
          throw new Error(`Unknown ${category} unit: ${from}. Available: ${Object.keys(conversions).filter(k => conversions[k] !== null).join(', ')}`);
      }
      if (!toKey) {
          throw new Error(`Unknown ${category} unit: ${to}. Available: ${Object.keys(conversions).filter(k => conversions[k] !== null).join(', ')}`);
      }
  
      // Same unit, trivial
      if (fromKey === toKey) {
          return JSON.stringify({ value, from: fromKey, to: toKey, result: value });
      }
  
      let result;
  
      // Temperature needs special handling (non-linear)
      if (category === 'temperature') {
          result = convertTemperature(value, fromKey, toKey);
      } else {
          // Convert: source → base unit → target
          const sourceToBase = conversions[fromKey];
          const targetToBase = conversions[toKey];
          // Value in base unit = value * sourceToBase
          // Target value = valueInBase / targetToBase
          result = (value * sourceToBase) / targetToBase;
      }
  
      return JSON.stringify({
          value,
          from: fromKey,
          to: toKey,
          result: parseFloat(result.toPrecision(15)),
          category,
      });
  },