metrick

    0.2.0 • Public • Published

    📏 Metrick

    npm metrick Build Status codecov

    Babel-powered unit magick

    Introduction

    Metrick is a library which allows you to convert units and avoid using magic numbers! In combination with a JavaScript syntax extension included with Babel, it allows for a new, clean and human-like syntax for doing so.

    For example;

    import { seconds, minute, milliseconds } from 'metrick/duration';
     
    // Explicit syntax
    setTimeout(
      () => console.log('1 minute has passed!'),
      1::minute.in(milliseconds)
    );
     
    // Implicit syntax
    setTimeout(
      () => console.log('30 seconds have passed!'),
      30::seconds
    );

    Here, two syntaxes are demonstrated; explicit and implicit!

    Explicit syntax

    import { gibibyte, megabytes } from 'metrick/data';
    import { years, days } from 'metrick/duration';
     
    console.log(1::gibibyte.in(megabytes)); // => 1073.741824
    console.log(25::years.in(days));        // => 9132.5

    The explicit syntax makes use of an in function to convert the original unit into another supplied unit. Passing a valid Unit object of the same type to in will return the result as a number.

    Implicit syntax

    import { megabits } from 'metrick/data';
    import { hours } from 'metrick/duration';
     
    console.log(50::megabits); // => 50000000
    console.log(24::hours);    // => 86400000

    Implicit syntax will convert the number to the default unit of the type of unit you're using. For instance, Data units implicitly convert to bits, and Duration units implicitly convert to milliseconds.

    In general, the implicit unit is the applicable SI base unit, however, in the case of Duration the implicit unit is milliseconds, for compatibility with standard JavaScript methods which deal with time.

    Shoutout to Glen Maddern for the idea behind implicit syntax

    Usage

    Note: This presumes you already use Babel to transpile your project's JavaScript. If you don't, instructions are available on Babel's website

    Configure Babel to transform function bind syntax by installing babel-plugin-transform-function-bind with your favourite Node package management tool, and then adding the plugin to your .babelrc;

    {
      "plugins": [
        "transform-function-bind"
      ]
    }

    Custom unit types

    A base Unit constructor exists, which you can extend to create your own classes of unit. All you need to do is extend it!

    For instance, here's an implementation of an Illuminance unit type (a unit unlikely to be included with Metrick 😜);

    import Unit from 'metrick/unit';
     
    export default class Illuminance extends Unit {
      // No overrides are necessary; we're using classes to check for conversion compatibility!
    }
     
    // SI base unit, implicit unit
    export default const lux = new Illuminance();
     
    export default const footcandle = new Illuminance(10.763910417::lux);
    // pluralise for better readability
    export default const footcandles = footcandle;
     
    export default const lumenPerSquareInch = new Illuminance(1550.0031::lux);
     
    export default const phot = new Illuminance(10000::lux);

    Custom units

    Each type of unit exposes a constructor to create a compatible unit type. The constructors accept two forms of defining the relationship between units;

    • One Number argument, indicating the multiplier between the unit and the base unit
    • Two Functions, each accepting one numeric argument and transform to and from the base unit

    For instance, here's an implementation of .beats as a Duration unit, using the multiplier argument;

    import Duration, { days, seconds, minutes } from 'metrick/duration';
     
    // each .beat is 1/1000th of a day, Durations are measured in seconds
    const dotBeat = new Duration((1 / 1000)::days.in(seconds));
     
    // pluralise for better readability
    const dotBeats = dotBeat;
     
    console.log(1::dotBeat.in(minutes));   // => 1.4400000000000002
    console.log(12::dotBeats.in(minutes)); // => 17.280000000000005

    As an example of providing Functions, here's an implementation of a Gas Mark temperature conversion;

    import Temperature, { celsius } from 'metrick/temperature';
     
    const gasMark = new Temperature(
      (temperature) => (
        temperature * 14 + 394.15
      ),
     
      (temperature) => (
        (temperature - 394.15) / 14
      )
    );
     
    console.log(1::gasMark.in(celsius)); // => 135
    console.log(5::gasMark.in(celsius)); // => 191

    Included units

    Currently, Metrick includes units for Data and Duration.

    Note: All built-in units are exported with their singular and plural names - here we only list plural for brevity.

    Data

    • bits (SI base unit, implicit unit)
    • bytes
    • exabits
    • exabytes
    • exbibits
    • exbibytes
    • gibibits
    • gibibytes
    • gigabits
    • gigabytes
    • kibibits
    • kibibytes
    • kilobits
    • kilobytes
    • mebibits
    • mebibytes
    • megabits
    • megabytes
    • nibbles
    • pebibits
    • pebibytes
    • petabits
    • petabytes
    • tebibits
    • tebibytes
    • terabits
    • terabytes

    Duration

    • days
    • hours
    • milliseconds (implicit unit)
    • minutes
    • months
    • seconds (SI base unit)
    • weeks
    • years

    Length

    Metric
    • centimetres
    • kilometres
    • metres (SI base unit, implicit unit)
    • millimetres
    Imperial
    • chains
    • feet (singular is foot)
    • inches (singular is inch)
    • miles
    • paces
    • yards
    Weird
    • spats
    • twips
    • astronomicalUnits

    Temperature

    Note: Built-in temperature units are exported both with and without degrees prefix - here we only list without for brevity.

    • celsius
    • fahrenheit
    • kelvin (SI base unit, implicit unit)

    Full-library export

    The library also includes a main entry point at index.js, which exposes all the available parts of the library. This is not recommended as if, for example, you Webpack the whole library, you'll include conversions you may not be using!

    import { Duration as DurationConstructor, duration } from 'metrick';
    import Duration, { minute } from 'metrick/duration';
     
    console.log(DurationConstructor === Duration) // => true
    console.log(duration.minute === minute);      // => true

    Wait, how does this work?

    This is making use of the function bind syntax extension. This extension adds a :: operator to JavaScript, which binds functions following to objects immediately before.

    Caveats

    This syntax extension is experimental - it's not even in any specification, merely a proposal which happens to have a transform available in Babel.

    Likewise, this is technically a bit of an abuse of this; implicit syntax takes advantage of the fact that the bind operator implicitly makes a call to the bind method of what is supposed to be a supplied function, and instead returns the implicit unit conversion in these cases.

    Also, technically, the function bind proposal suggests that the syntax check that the function passed is callable, but Babel's transform does not test this. Metrick instead uses an object which happens to have a bind method, so this particular approach may break in more strict, future versions of the transformation - but hopefully not!

    Install

    npm i metrick

    DownloadsWeekly Downloads

    15

    Version

    0.2.0

    License

    MIT

    Last publish

    Collaborators

    • ticky