uom-tools

A modern TypeScript/JavaScript library for parsing and formatting units of measure (UOM). Supports both CommonJS and ES modules, making it perfect for modern applications like TanStack Start, Next.js, and other TypeScript projects.

Features

• Length Units: millimeters, centimeters, meters, decimal inches, fractional inches (16ths, 32nds, 64ths), feet, and combinations
• Volume Units: milliliters and fluid ounces
• Modern TypeScript: Full TypeScript support with type definitions
• Dual Package: Supports both CommonJS and ES modules
• Tree Shakeable: ES module exports for optimal bundle sizes

Installation

npm install uom-tools
# or
pnpm add uom-tools
# or
yarn add uom-tools

Usage

ES Modules (Recommended)

import {
  formatLength,
  parseLength,
  formatVolume,
  parseVolume,
} from "uom-tools";

// Format length
console.log(formatLength(5, "in", "cm")); // "12.7"
console.log(formatLength(5, "in", "ft_in")); // "5\""

// Parse length
console.log(parseLength("5' 4\"", "in")); // 64
console.log(parseLength("10' 4-1/2\"", "in")); // 124.5

// Format volume
console.log(formatVolume(100, "mL", true)); // "100 mL"
console.log(formatVolume(100, "oz", true)); // "3.4 oz"

// Parse volume
console.log(parseVolume("100", "mL")); // 100
console.log(parseVolume("3.4", "oz")); // 0.10055...

CommonJS

const { formatLength, parseLength } = require("uom-tools");

console.log(formatLength(5, "in", "cm")); // "12.7"
console.log(parseLength("5' 4\"", "in")); // 64

API Reference

Length Functions

formatLength(value, fromUnit, toUnit, displayFormat?, showUnits?)

Formats a length value from one unit to another.

• value: The numeric value to format
• fromUnit: Source unit ("mm", "cm", "m", "in", "ft")
• toUnit: Target unit ("mm", "cm", "m", "in", "ft", "ft_in")
• displayFormat: For inches - "in" (decimal), "in16", "in32", "in64" (fractional)
• showUnits: Whether to include unit symbols

parseLength(input, targetUnit, defaultUnit?)

Parses a length string into a numeric value.

• input: String to parse (e.g., "5' 4\"", "10 cm", "5-1/2\"")
• targetUnit: Unit to convert to
• defaultUnit: Default unit if none specified in input

Volume Functions

formatVolume(value, fromUnit, showUnits?)

Formats a volume value.

• value: The numeric value to format
• fromUnit: Source unit ("mL", "oz")
• showUnits: Whether to include unit symbols

parseVolume(input, targetUnit)

Parses a volume string into a numeric value.

• input: String to parse (e.g., "100 mL", "3.4 oz")
• targetUnit: Unit to convert to

Examples

Length Formatting

import { formatLength } from "uom-tools";

// Basic conversions
formatLength(5, "in", "cm"); // "12.7"
formatLength(100, "cm", "ft"); // "3.28"

// Fractional inches
formatLength(5.0625, "in", "in", "in16"); // "5-1/16"
formatLength(5.03125, "in", "in", "in32"); // "5-1/32"

// Feet and inches
formatLength(64, "in", "ft_in"); // "5' 4\""
formatLength(64.5, "in", "ft_in"); // "5' 4-1/2\""

// With units
formatLength(5, "in", "cm", undefined, true); // "12.7 cm"

Length Parsing

import { parseLength } from "uom-tools";

// Parse various formats
parseLength("5' 4\"", "in"); // 64
parseLength("10' 4-1/2\"", "in"); // 124.5
parseLength("10 cm", "in"); // 3.94
parseLength('5-1/2"', "in"); // 5.5
parseLength("100 mm", "cm"); // 10

Volume Formatting

import { formatVolume } from "uom-tools";

// Format volumes
formatVolume(100, "mL", true); // "100 mL"
formatVolume(100, "oz", true); // "3.4 oz"
formatVolume(1000, "mL", true); // "1,000 mL"

Volume Parsing

import { parseVolume } from "uom-tools";

// Parse volumes
parseVolume("100", "mL"); // 100
parseVolume("3.4", "oz"); // 0.10055...
parseVolume("1,000", "mL"); // 1000

TypeScript Support

The package includes full TypeScript definitions:

import type { LengthUOM, VolumeUOM } from "uom-tools";

// Length units: "mm" | "cm" | "m" | "in" | "ft"
// Volume units: "mL" | "oz"

Modern Framework Support

This package works seamlessly with modern frameworks:

• TanStack Start: Full ES module support
• Next.js: Works with both App Router and Pages Router
• Vite: Optimized for Vite's ES module handling
• Node.js: Both CommonJS and ES module support

License

MIT