Getting started

Install with npm:

npm install @coreify/unit

Unit works in TypeScript and JavaScript. Default behavior stays canonical:

• unit ids stay English-style canonical ids like kg, sq_ft, km
• formatted output stays non-localized unless you opt into unit localization
• localized aliases are accepted when input actually contains them

First import

import {
  bestUnit,
  convert,
  convertDetailed,
  createMeasurementSchema,
  formatMeasurement,
  normalizeMixedMeasurement,
  parseMeasurement,
} from "@coreify/unit"

convert(1, "km", "m") // 1000
formatMeasurement(12.5, "kg") // "12.5 kg"
parseMeasurement("১২.৫০ কেজি") // { value: 12.5, unit: "kg", rawUnit: "কেজি", decimalPlaces: 2 }
normalizeMixedMeasurement("5 ft 7 in", "in") // 67
bestUnit(1532, "m") // { value: 1.532, unit: "km", formatted: "1.532 km" }
convertDetailed(1, "bigha", "sq_ft") // { value, rawValue, baseValue, factors, status, warnings }

What to use first

Start with this mental model:

• convert for plain compatible-unit conversion
• convertDetailed when app must inspect trace, status, or warnings
• parseMeasurement for single value + unit input like 12.5 kg
• normalizeMixedMeasurement for mixed strings like 5 ft 7 in
• bestUnit when UI should choose readable output automatically
• formatMeasurement when app already has numeric value + canonical unit

Default output vs localized output

Default output:

formatMeasurement(12.5, "kg")
// "12.5 kg"

Localized digits are opt-in via locale. Localized unit names are separate opt-in:

formatMeasurement(12.5, "kg", {
  locale: "bn-BD",
  unitDisplay: "label",
})
// "১২.৫ kilogram"

formatMeasurement(12.5, "kg", {
  locale: "bn-BD",
  unitDisplay: "label",
  localizeUnits: true,
})
// "১২.৫ কিলোগ্রাম"

Good production pattern

For most apps:

1. Parse incoming user input.
2. Normalize to canonical unit before storing.
3. Convert only at presentation or export boundary.
4. Use localized formatting only in UI paths that need it.

Error messages

Unit now throws user-facing error messages that explain what to fix.

parseMeasurement("banana")
// InvalidMeasurementError:
// Could not read "banana" as measurement. Use format like "12.5 kg" or "5 ft".

const schema = createMeasurementSchema({ required: true })
schema.parse("")
// InvalidMeasurementError:
// Measurement is required. Enter value with unit like "12 kg".

That makes form errors, import errors, and API validation errors easier to surface directly.

Benchmarks

Package ships micro-bench harness for perf regression tracking.

bun run bench
bun run bench --json
bun run bench --csv
bun run bench --json --repeats 9 --sample-ms 1200

Use JSON or CSV modes for CI artifacts and before/after comparison.

Package shape

Unit has no runtime dependencies and ships:

• ESM
• CommonJS
• TypeScript declarations

That keeps it safe for frontend apps, Node services, CLIs, admin tools, and ETL scripts.