gen-unit

A generic unit parser/formatter generator

Index

• Install
• Parser
  • function createParser
  • function parse
  • parser options
    • option unit
    • option match
      • as a RegExp
      • as a string
      • as a function
    • option find
      • as a number
      • as an array
      • as an object
      • as a function
• Formatter
  • function createFormatter
  • function format
  • formatter options
    • option unit
    • option find
      • as a number
      • as an array
      • as an object
      • as a function
    • option round
      • as an object
      • as a number
      • as a function
      • as a boolean
    • option output
      • as an object
      • as a function
• Constants
  • constant MICRO
• Types
  • type Parser
  • type ParserOptions
  • type Formatter
  • type FormatterOptions

Install

# Using npm
npm install gen-unit

# Using yarn
yarn add gen-unit

# Using pnpm
pnpm add gen-unit

Parser

function createParser

Creates a parser function using the given parser options.

function createParser(options: ParserOptions): Parser;

see also: parser options, type ParserOptions, type Parser

function parse

A convenient function to parse an input in one step. I will internally call createParser with the given parser options, then will call the newly created parser.

function parse(input: unknown, options: ParserOptions): number;

see also: function createParser, parser options, type ParserOptions, type Parser

parser options

parser option unit

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 m'); // => 0.001
parse('1 mg'); // => 0.001
parse('1 k'); // => 1000
parse('1 kg'); // => 1000
parse('1 ms'); // => NaN because "s" is not recognized as unit

Precedence

This option takes precedence over any prefix or prefixed unit.

Examples

const parseDistance = createParser({
  unit: 'm', // Meter
});

parseDistance('1 m'); // returns 1 (1 meter)
parseDistance('1 mm'); // returns 0.001 (1 millimeter)

const parseSeconds = createParser({
  unit: 's' // Seconds
});

parseSeconds('1 m'); // returns 0.001 (1 millisecond)
parseSeconds('1 ms'); // returns 0.001 (1 millisecond)

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

parse('1 meg'); // => 0.001 (not 1000000), it's interpreted as 1 milli-eg
parse('1 megeg'); // => 1000000, it's interpreted as 1 mega-eg
parse('1 Meg'); // => 1000000, it's interpreted as 1 mega-eg because capital "M" parses as mega

parser option match

match: RegExp | string | MatchFunction;

type MatchFunction = (input: string) => [value: string, unit: string] | null | undefined;

default /^\s*(-?\d*\.?\d*(?:e[+-]?\d+)?)\s*([a-z\xb5]*)\s*$/i

Defines the first step in the parse process (tokenization), it takes the input and should turn it into an array with two elements, the value, and the unit to be process further down the road, or null (or undefined) if the input can't be tokenized.

parser option match as a RegExp

match: RegExp;

default /^\s*(-?\d*\.?\d*(?:e[+-]?\d+)?)\s*([a-z\xb5]*)\s*$/i

A RegExp with two capturing groups, the first to be used as value and the second as unit. If the RegExp has less than two capturing groups, parse function will throw.

Example

const parseOnlyIntegers = createParser({
  match: /^\s*(-?\d+)\s*([a-z]*)\s*$/i,
});

parseOnlyIntegers('1 m'); // => 0.001
parseOnlyIntegers('-1 k'); // => -1000

parser option match as a string

match: string;

A string to be used to create a RegExp. It is expected to have two capturing groups, the first to be used as value and the second as unit. Keep in mind the RegExp create from this string will be case sensitive.

Example

const parse = createParser({
  match: '^\\s*(-?\\d+)\\s*([a-z]*)\\s*$',
});

parse('1 m'); // => 0.001
parse('-1 k'); // => -1000

parser option match as a function

match: (input: string) => [value: string, unit: string] | null | undefined;

A function which will receive the input and should return an array of two elements, the first to be used as value and the second as unit, or null (or undefined) if the input can't be parsed.

Example

const parse = createParser({
  match(input) {
    return [input, 'k']
  },
});

parse('1'); // => 1000
parse('2'); // => 2000

parser option find

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

parser option find as a number

find: number;
default 1000

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

parser option find as an array

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

An array of objects describing prefixes (pre) and exponents (exp) to use with the default base (1000) to find the multiplier to be used during parsing. Every item should have a unique prefix, if there are duplicates createParser will throw.

notes

Note that empty prefix ({ pre: '', exp: 0 }) is not necessary, as an empty prefix will result in multiplier = 1

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 because prefix "G" can't be found

parser option find as an object

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

default: {
  base: 1000,
  items: [
    { pre: 'a', exp: -6 },
    { pre: 'f', exp: -5 },
    { pre: 'p', exp: -4 },
    { pre: 'n', exp: -3 },
    { pre: 'u', exp: -2 },
    { pre: 'µ', 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 },
    { pre: 'P', exp: 5 },
    { pre: 'E', exp: 6 },
  ],
}

An object describing the base and a series of objects describing prefixes and exponents to find the multiplier to be used during parsing. Every item in items array should have a unique pre, if there are duplicates createParser will throw.

Notes

Note that empty prefix ({ pre: '', exp: 0 }) is not necessary, as an empty prefix will result in multiplier = 1

Example

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

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

parser option find as a function

find: (pre: string) => number | null | undefined;

A function that should return a non-zero number by which the parsed value should be multiplied based on the captured prefix. Return null (or undefined) if multiplier can't be determined. It will cause the parse function to return NaN. If your function returns zero, negative number or any other invalid multiplier, parse function will throw a TypeError.

Example

const parse = createParser({
  find: (unit) => {
    if (unit === 'K' || unit === 'k') {
      return 1024;
    } else if (unit === 'M') {
      return 1024 ** 2;
    }
    // next line can be omitted
    // as it will return undefined anyway
    return null;
  },
});

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

Notes

Previous version of this library allow this function to return an object { mul: number } containing the multiplier. This behavior has been removed, it will throw instead.

Formatter

function createFormatter

Creates a formatter function using the given formatter options.

function createFormatter(options: FormatterOptions): Formatter;

see also: formatter options, type FormatterOptions, type Formatter

function format

A convenient function to format a number in one step. It wil internally call createFormatter with given formatter options then will call the newly created formatter.

function format(input: number, options: FormatterOptions): string;

see also: function createFormatter, formatter options, type FormatterOptions, type Formatter

formatter options

formatter option unit

A string to be used as main unit during formatting.

unit: string;

Example

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

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

formatter option find

Describes how to find the unit prefix and divider based on input value.

formatter option find 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'

formatter option find as an array

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

An array of objects describing prefixes and exponents to use with the default base (1000) to find the prefix and multiplier to be used during formatting. Every item should have a unique exp, if there are duplicates createFormatter will throw.

Example

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

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

formatter option find as an object

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

default: {
  base: 1000,
  items: [
    { exp: -6, pre: 'a' },
    { 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' },
    { exp: 5, pre: 'P' },
    { exp: 6, pre: 'E' },
  ],
}

An object describing the base and a series of objects describing prefixes and exponents to find the prefix and multiplier to be used during formatting. Every item in items array should have a unique exp, if there are duplicates createFormatter will throw.

Example

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

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

formatter option find as a function

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

A function that returns an object describing the unit prefix (pre) and multiplier (mul).

Example

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

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

formatter option round

Describes how to round the output value before final format.

formatter option round as an object

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

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

An object describing how to round the value before final format. Describes the number of decimal (dec) and whether or not the output should have a fixed number of decimal (fixed).

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'

formatter option round 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(1.28); // => '1.3'
format(1230); // => '1.2 k'
format(0.00123); // => '1.2 m'

formatter option round as a function

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

A function which returns the rounded value.

Example

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

format(1.23); // => '1'
format(1.75); // => '2'
format(1230); // => '1 k'
format(0.00123); // => '1 m'

formatter option round as a boolean

round: boolean;

A boolean defining wether or not to round the number. If true is passed, the default rounder will be used (2 decimals). If false is passed, rounding will be disabled.

Example

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

format(1.231); // => '1.23'
format(1.238); // => '1.24'
format(1200); // => '1.2 k'
format(0.001234); // => '1.23 m'

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

format(1.234); // => '1.234'
format(1.28); // => '1.28'
format(1233); // => '1.233 k'
format(0.0012); // => '1.2 m'

Keep in mind disabling the rounder will case the the output to receive the value in it's raw form and you might get unpredictable results, see example...

Example

const format = createFormatter({});
const formatWithoutRounding = createFormatter({ round: false });

const pointThree = 0.1 + 0.2; // in javascript 0.1 + 0.2 = 0.30000000000000004

format(pointThree); // => '0.3'
formatWithoutRounding(pointThree); // => '0.30000000000000004'

const threeThousand = pointThree * 10000; // 3000.0000000000005

format(threeThousand); // => '3 k'
formatWithoutRounding(threeThousand); // => '3000.0000000000005 k'

formatter option output

Describes the final output format.

output: FormatOutputFunction | FormatOutputAdvancedOption;

type FormatOutputFunction = (value: string | number, prefix: string, unit: string) => string;

interface FormatOutputAdvancedOption {
  space: string;
}

formatter option output as an object

output: {
  space?: string;
}

default {
  space: ' ';
}

Example

const format = createFormatter({
  output: {
    space: '-', // unrealistic, for demonstration only
  },
})

format(1.23); // => '1.23'
format(1230); // => '1.23-k'
format(0.00123); // => '1.23-m'

formatter option output as a function

A function to format the final output.

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

Example

const format = createFormatter({
  unit: 'x',
  output: (value, pre) => {
    // ignore original unit and hardcode one
    return `${value}${pre}s`;
  },
});

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

Constant

constant MICRO

A constant containing the micro symbol ("µ"). Used internally, exported for convenience.

Types

type Parser

type Parser = (input: unknown): number

see also: function createParser, function parse.

type ParserOptions

type ParserOptions = object // ...coming later

see also: function createParser, function parse.

type Formatter

type Formatter = (value: number) => string

see also: function createFormatter, function format.

type FormatterOptions

type FormatterOptions = object // ...coming later

see also: function createFormatter, function format.

License

MIT © 2019-2025 Manuel Fernández