gen-unit

A generic unit parser/formatter

Install

# Using npm
npm i gen-unit

# Using yarn
yarn add gen-unit

API

createParser

Creates a parse function using the given options.

function createParser(options): ParseFunction;

type ParseFunction = (input: string | number | object) => number;

Options

unit

The "unit" option defines the unit to be used during parsing.

unit: string;

example

const parse = createParser({
  unit: 'g',
});

parse('1'); // => 1
parse('1 g'); // => 1
parse('1 mg'); // => 0.001
parse('1 K'); // => 1000
parse('1 Kg'); // => 1000
parse('1 ms'); // => NaN

• Precedence

This option takes precedence over any prefix or prefixed unit.

examples

const parse = createParser({
  unit: 'm',
});

parse('1 m'); // => 1  (not 0.001)
parse('1 mm'); // => 0.001

const parse = createParser({
  unit: 'eg', // assume "eg" is the unit... for some reason
});

parse('1 meg'); // => 0.001 (not 1000000)
parse('1 megeg'); // => 1000000
parse('1 Meg'); // => 1000000

find

The "find" option describes how to find the number by which the parsed value should be multiplied.

• "find" option as an object

find: {
  base?: number;
  find?: Array<{ pre: string; exp: number }>;
};

default: {
  base: 1000,
  find: [
    { pre: 'f', exp: -5 },
    { pre: 'p', exp: -4 },
    { pre: 'n', exp: -3 },
    { pre: 'u', exp: -2 },
    { pre: 'm', exp: -1 },
    { pre: 'k', exp: 1 },
    { pre: 'K', exp: 1 },
    { pre: 'meg', exp: 2 },
    { pre: 'M', exp: 2 },
    { pre: 'G', exp: 3 },
    { pre: 'T', exp: 4 },
  ],
}

An object describing the base and unit prefixes to find the multiplier.

example

const parse = createParser({
  find: {
    base: 1024,
    find: [
      { pre: 'K', exp: 1 },
      { pre: 'M', exp: 2 },
    ],
  },
});

parse('1'); // => 1
parse('1 K'); // => 1024
parse('1 M'); // => 1048576
parse('1 G'); // => NaN

• "find" option as a number

find: number;

A number to be used as base during parsing.

example

const parse = createParser({
  find: 1024,
});

parse('2'); // => 2
parse('2 K'); // => 2048
parse('2 M'); // => 2097152
parse('2 G'); // => ‭‭‭2147483648‬

• "find" option as an array

find: Array<{ pre: string; exp: number }>;

An array of objects describing the different units prefixes.

example

const parse = createParser({
  find: [
    { pre: 'K', exp: 1 },
    { pre: 'M', exp: 2 },
  ],
});

parse('1.3'); // => 1.3
parse('1.3 K'); // => 1300
parse('1.3 M'); // => 1300000
parse('1.3 G'); // => NaN

• "find" option as a function

find: (unit: string) => number;

A function that returns a number by which the parsed value should be multiplied based on the captured unit.

example

const parse = createParser({
  find: (unit) => {
    if (unit === 'K' || unit === 'k') {
      return 1024;
    } else if (unit === 'M') {
      return 1024 ** 2;
    }
  },
});

parse('2'); // => 2
parse('2 K'); // => 2048
parse('2 M'); // => 2097152
parse('2 G'); // => NaN

createFormatter

Creates a format function using the given options.

function createFormatter(options): FormatFunction;

type FormatFunction = (input) => string;

Options

unit

The "unit" option defines the unit to be used during formatting.

• "unit" option as a string

unit: string;

A string to be used as main unit.

example

const format = createFormatter({
  unit: 'm',
});

format(100); // => '100 m'
format(0.0012); // => '1.2 mm'
format(1200); // => '1.2 Km'

• "unit" option as a function

unit: (value: number, rounded: string | number, pre: string) => string;

A function that returns the unit based on parameters.

example

const format = createFormatter({
  unit: (value, rounded, pre) => {
    return 'm';
  },
});

format(100); // => '100 m'
format(0.0012); // => '1.2 mm'
format(1200); // => '1.2 Km'

find

The "find" option describes how to find the unit prefix based on input value.

• "find" option as an object

find: {
  base?: number;
  find?: Array<{ exp: number; pre: string }>;
}

default: {
  base: 1000,
  find: [
    { exp: -5, pre: 'f' },
    { exp: -4, pre: 'p' },
    { exp: -3, pre: 'n' },
    { exp: -2, pre: 'µ' },
    { exp: -1, pre: 'm' },
    { exp: 0, pre: '' },
    { exp: 1, pre: 'K' },
    { exp: 2, pre: 'M' },
    { exp: 3, pre: 'G' },
    { exp: 4, pre: 'T' },
  ],
}

example

const format = createFormatter({
  find: {
    base: 1024,
    find: [
      { exp: 0, pre: '' },
      { exp: 1, pre: 'K' },
    ],
  },
});

format(100); // => '100'
format(2048); // => '2 K'
format(2097152); // => '2048 K'

• "find" option as a number

find: number;

A number to be used as base during formatting.

example

const format = createFormatter({
  find: 1024,
});

format(100); // => '100'
format(2048); // => '2 K'
format(2097152); // => '2 M'

• "find" option as an array

find: Array<{ exp: number; pre: string }>;

An array of objects describing the different unit prefixes.

example

const format = createFormatter({
  find: [
    { exp: 0, pre: '' },
    { exp: 1, pre: 'K' },
  ],
});

format(2); // => '2'
format(2000); // => '2 K'
format(2000000); // => '2000 K'

• "find" option as a function

find: (value: number) => { div: number; pre: string };

A function that returns an object describing the unit prefix.

example

const format = createFormatter({
  find: (value) => {
    if (value >= 1000) {
      return { pre: 'K', div: 1000 };
    } else {
      return { pre: '', div: 1 };
    }
  },
});

format(2); // => '2'
format(2000); // => '2 K'
format(2000000); // => '2000 K'

round

The "round" option describes how to round the value.

• "round" option as an object

round: {
  dec?: number;
  fixed?: boolean;
};

default: {
  dec: 2,
  fixed: false,
};

An object describing how to format the value.

example

const format = createFormatter({
  round: {
    dec: 3,
    fixed: true,
  },
});

format(1.23); // => '1.230'
format(1230); // => '1.230 K'
format(0.00123); // => '1.230 m'

• "round" option as a number

round: number;

A number defining the number of decimal places to round to.

example

const format = createFormatter({
  round: 1,
});

format(1.23); // => '1.2'
format(1230); // => '1.2 K'
format(0.00123); // => '1.2 m'

• "round" option a function

round: (num: number) => (string | number);

A function that returns a rounded value.

example

const format = createFormatter({
  round: Math.round,
});

format(1.23); // => '1'
format(1230); // => '1 K'
format(0.00123); // => '1 m'

output

A function to format the final output.

output: (value: string | number, pre: string, unit: string) => (string | number);

example

const format = createFormatter({
  output: (value, pre) => `${value}${pre}s`,
})

format(1.23); // => '1.23s'
format(1230); // => '1.23Ks'
format(0.00123); // => '1.23ms'

parse

A convenient function to parse an input in one step.

function parse(input, options): number;

format

A convenient function to format a number in one step.

function format(input, options): string;

License

MIT © Manuel Fernández