Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ClickerMonkey/unitz-ts

A unit parser, converter, & calculator for TypeScript and JS
https://github.com/ClickerMonkey/unitz-ts

Last synced: about 2 months ago
JSON representation

A unit parser, converter, & calculator for TypeScript and JS

Awesome Lists containing this project

README 

        
# Unitz



A unit parser, converter, & calculator for TypeScript and JS.



- [Documentation](https://clickermonkey.github.io/unitz-ts/docs/)

- [Online Tool](https://clickermonkey.github.io/unitz-ts/tester.html)

- Installation `npm install unitz-ts`, `bower install unitz-ts`, [download](https://github.com/ClickerMonkey/unitz-ts/tree/master/umd)



```javascript

// TypeScript

import { uz, Classes } from 'unitz-ts';



// Add built-in units

Classes.addDefaults(); 



// Javascript

var uz = Unitz.uz;



Unitz.Classes.addDefaults(); // Add built-in units



// Parsing

uz('2.5 cups'); // parses numbers

uz('1/2 in'); // parses fractions

uz('3 1/4'); // mixed fractions and unitless values

uz('mile'); // implicit values (1)

uz('4-5 seconds'); // parses ranges

uz('4s - 3min'); // parses ranges with mixed units

uz('2c, 4s, 23mi'); // mixed unit classes

uz('23 m/s, 60 mph, 2 1/2 liters per second'); // rates



// Transformations

uz('1.5 pints').normalize(); // = 3 cups: convert to unit in same class which is more human friendly

uz('1c, 1pt').compact(); // = 1.5 pt: join values in the same unit class together

uz('43in').expand(); // = 3 ft, 7 in: pull unit values of the same class apart to be more human friendly



// Operations

uz('1 pt').add('1 cup').normalize(); // = 3 cups

uz('1 pt').sub('1 cup').normalize(); // = 1 cup

uz('1 pt, 3 in').scale(2); // = 2 pt, 6 in

uz('1 pt, 3 in').scaleTo('6 c'); // = 3 pt, 9 in



// Convert

uz('1 - 2 gal').convert('c'); // = 16 - 32 c

uz('3 cup').conversions(); // = 3/16 gal, 3/4 qt, 1 1/2 pt, 3 c, 24 floz, 48 tbsp, 144 tsp



// Mutations

uz('3 cups').preferred(); // = 3 c: convert units to preferred

uz('-2 in, 4 mi, -2 - 2').positive(); // = 4 mi, 0 - 2: we only want positive

uz('-2 in, 4 mi, -2 - 2').negative(); // = -2 in, -2 - 0: we only want negative

uz('-2 in, 4 mi, 0 tacos').nonzero(); // = -2 in, 4 mi: we only want non-zero

uz('-2 in, 4 mi, -2 - 2').min(); // = -2 in, -2: we only the minimum values of a range

uz('-2 in, 4 mi, -2 - 2').max(); // = -2 in, 2: we only the maximum values of a range

uz('0.5 tsp').fractions(); // = 1/2 tsp: convert to fractions

uz('1/2 tsp').numbers(); // = 0.5 tsp: convert to numbers



// Sorting

uz('1 tsp, 1 pt, 4 gal').sort(); // = 4 gal, 1 pt, 1 tsp: sort values



// Dynamic unit groups

uz('1 loaf').add('4 loaves').normalize(); // = 5 loaves



// Output

uz('1 cup').output( options ); // the above functions return objects, to get a string you must call output which can take options to override the global output options.



// Alternative Input Formats

uz({ value: 34, unit: 'ms' }); // a single number value

uz({ num: 4, den: 12, unit: 'c' }); // a single fraction value

uz({ min: '4c', max: '8c' }); // a range with value strings

uz({ min:{value:1}, max:{value:2, unit:'m'} }); // range with value objects

uz([ '4c', '1-2m' ]); // range list of range/value strings

uz([ {value: 34, unit: 'ms'}, {min:'1m', max:'2m' ]); // range list of range/value objects



// Translations

Unitz.Translations.addDefaults();



uz('one pound'); // = 1 pound

uz('dozen tacos'); // = 12 tacos

uz('an eleven meters'); // = 11 meters

uz('a third of an acre'); // = 1/3acre

uz('half a dozen eggs'); // = 6eggs

uz('a seventh of a mile'); // = 1/7mile

uz('23 and a half eggs'); // = 23 1/2eggs

uz('one and a half acres'); // = 1 1/2acres

uz('23 and a third'); // = 23 1/3

uz('12 and one fourth cups'); // = 12 1/4cups

uz('(one and a half) acre'); // = 1 1/2acre

uz('(12) tacos'); // = 12 tacos

uz('1 (6 ounce)'); // = 6ounce

uz('5 (3 liter)'); // = 15liter



// Rates (aliases)

Unitz.Rates.addDefaults();



uz('60 mph');; // 60 miles/hour

uz('23 knots');; // 23 nautical miles/hour

```



### Customization



You can customize exactly how Unitz behaves.



```javascript

// The "distance" used to determine if a value is close enough to 0, 1, or if a calculated fraction is close enough to the real value.

Unitz.Functions.EPSILON = 0.001;



// The default settings for outputting values

Unitz.Core.globalOutput;



// The default settings for transforms

Unitz.Core.globalTransform;



// The default settings for sorting

Unitz.Core.globalSort;



// When preferred() is ran, use this unit

Unitz.Core.setPreferred( 'cup' );



// Set this unit group as common or uncommon

Unitz.Core.setCommon( 'cup', false ); // we don't use cups round these parts



// Set the denominators available for a unit group

Unitz.Core.setDenominators( 'cup', [2, 3, 4, 5, 6] );



// Add some units to an existing group

Unitz.Core.getGroup('cup').addUnits({

  'cupz': Unitz.Plurality.PLURAL

});



// Remove some units from an existing group

Unitz.Core.getGroup('c').removeUnits(['cup', 'cups']);



// Add my own rate

Unitz.Rates.add('feet', 'second', ['fps']);



// Add my own class

Unitz.Core.addClass(new Class('Loaf', [

  {

    system: Unitz.System.ANY,

    common: true,

    unit: 'loaf',

    baseUnit: 'loaf',

    denominators: [2, 3, 4, 5, 6, 7, 8, 9, 10],

    units: {

      'loaf': Unitz.Plurality.SINGULAR,

      'loaf of bread': Unitz.Plurality.SINGULAR,

      'loafs': Unitz.Plurality.PLURAL,

      'loaves': Unitz.Plurality.PLURAL,

      'loaves of bread': Unitz.Plurality.PLURAL

    }

  }

]));



// To create dynamic groups Unitz looks at the first 3 characters to determine if two units are matches. You can override this by figuring out a value which can be used as a key.

Unitz.Core.getDynamicMatch = function(unit) {

  // use soundex instead of the first three characters. cup and kup are equal now!

  return soundex( unit );

};



// To override the logic for determining what value is "normal" (most user friendly)

Unitz.Core.isMoreNormal = function(fromValue, toValue, transform, forOutput) {

  return true;

};

```



### Supported Units



**Angle**:

- deg, °, degree, degrees

- rad, radian, radians



**Area**:

- sqin, sq. in, sq in, in2, in^2, in², inch2, inch^2, inch², inches2, inches^2, inches², square in, square inch, square inches

- sqft, sq. ft, sq ft, ft2, ft^2, ft², foot2, foot^2, foot², feet2, feet^2, feet², square ft, square foot, square feet

- sqyd, sq. yd, sq yd, yd2, yd^2, yd², yard2, yard^2, yard², yards2, yards^2, yards², square yd, square yard, square yards

- acre, acres

- sqmi, sq. mi, sq mi, mi2, mi^2, mi², mile2, mile^2, mile², miles2, miles^2, miles², square mi, square mile, square miles

- sqmm, sq. mm, sq mm, mm2, mm^2, mm², millimeter2, millimeter^2, millimeter², millimeters2, millimeters^2, millimeters², square mm, square millimeter, square millimeters

- sqcm, sq. cm, sq cm, cm2, cm^2, cm², centimeter2, centimeter^2, centimeter², centimeters2, centimeters^2, centimeters², square cm, square centimeter, square centimeters

- sqm, sq. m, sq m, m2, m^2, m², meter2, meter^2, meter², meters2, meters^2, meters², square m, square meter, square meters

- sqkm, sq. km, sq km, km2, km^2, km², kilometer2, kilometer^2, kilometer², kilometers2, kilometers^2, kilometers², square km, square kilometer, square kilometers



**Digital**:

- b, bit, bits

- nibble, nibbles, nybble, nyble, half-byte, half byte, tetrade, semi-octent, quadbit, quartet

- B, byte, bytes

- kB, kilobyte, kilobytes

- mB, megabyte, megabytes

- gB, gigabyte, gigabytes

- tB, terabyte, terabytes

- pB, petabyte, petabytes

- eB, exabyte, exabytes

- zB, zettabyte, zettabytes

- yB, yottabyte, yottabytes

- KB, kibibyte, kibibytes

- MB, mebibyte, mebibytes

- GB, gibibyte, gibibytes

- TB, tebibyte, tebibytes

- PB, pebibyte, pebibytes

- EB, exbibyte, exbibytes

- ZB, zebibyte, zebibytes

- YB, yobibyte, yobibytes

- kb, kilobit, kilobits

- mb, megabit, megabits

- gb, gigabit, gigabits

- tb, terabit, terabits

- pb, petabit, petabits

- eb, exabit, exabits

- zb, zettabit, zettabits

- yb, yottabit, yottabits

- kibit, kibibit, kibibits

- mibit, mebibit, mebibits

- gibit, gibibit, gibibits

- tibit, tebibit, tebibits

- pibit, pebibit, pebibits

- eibit, exbibit, exbibits

- zibit, zebibit, zebibits

- yibit, yobibit, yobibits



**Length**:

- in, inch, inches, "

- ft, foot, feet, '

- yd, yard, yards, yds

- mi, mile, miles

- league, leagues

- mm, millimeter, millimeters, millimetre, millimetres

- cm, centimeter, centimeters, centimetre, centimetres

- dc, decimeter, decimeters, decimetre, decimetres

- m, meter, meters, metre, metres

- km, kms, kilometer, kilometers, kilometre, kilometres

- nm, nmi, nautical mi, nautical mile, nautical miles



**Temperature**:

- F, °F, Fahrenheit

- °C, Celsius

- K, kelvin, kelvins



**Time**:

- ns, nano, nanos, nanosecond, nanoseconds

- us, micro, micros, microsecond, microseconds

- ms, milli, millis, millisecond, milliseconds

- s, sec, secs, second, seconds

- min, mins, minute, minutes

- hr, hrs, hour, hours

- day, days

- wk, wks, week, weeks,

- yr, yrs, year, years

- score

- decade, decades

- biennium, bienniums

- triennium, trienniums

- quadrennium, quadrenniums

- lustrum, lustrums

- decade, decades

- century, centurys, centuries

- millennium, millenniums, millennia, millennias



**Volume**:

- ts, tsp, tsps, teaspoon, teaspoons

- tbsp, tbsp, tablespoon, tablespoons

- floz, fl-oz, fl oz, fluid ounce, fluid ounces, fl. oz, oz. fl, oz fl

- c, cup, cups

- pt, pint, pints,

- qt, quart, quarts

- gal gals, gallon, gallons

- ml, millilitre, millilitres, milliliter, milliliters

- cl, centilitre, centilitre, centiliter, centiliters

- l, litre, litres, liter, liters

- dl, decalitre, decalitres, decaliter, decaliters

- kl, kilolitre, kiloletres, kiloliter, kiloliters

- mm3, mm^3, mm³, millimeter3, millimeter^3, millimeter³, millimeters3, millimeters^3, millimeters³, cubic mm, cubic millimeter, cubic millimeters

- cm3, cm^3, cm³, centimeter3, centimeter^3, centimeter³, centimeters3, centimeters^3, centimeters³, cubic cm, cubic centimeter, cubic centimeters

- m3, m^3, m³, meter3, meter^3, meter³, meters3, meters^3, meters³, cubic m, cubic meter, cubic meters

- km3, km^3, km³, kilometer3, kilometer^3, kilometer³, kilometers3, kilometers^3, kilometers³, cubic km, cubic kilometer, cubic kilometers

- in3, in^3, in³, inch3, inch^3, inch³, inches3, inches^3, inches³, cubic in, cubic inch, cubic inches

- ft3, ft^3, ft³, foot3, foot^3, foot³, feet3, feet^3, feet³, cubic ft, cubic foot, cubic feet

- yd3, yd^3, yd³, yard3, yard^3, yard³, yards3, yards^3, yards³, cubic yd, cubic yard, cubic yards



**Weight**:

- mg, milligram, milligrams

- g, gram, grams

- kg, kilo, kilos, kilogram, kilograms

- oz, ounce, ounces

- lb, lbs, pound, pounds

- ton, tons, tonne, tonnes